├── .circleci └── config.yml ├── .gitignore ├── .travis.yml ├── CONTRIBUTING.md ├── Makefile ├── README.md ├── SUBMITTING.md ├── draft-ietf-acme-acme.md └── rfced ├── clean-xml.py ├── draft-ietf-acme-acme.clean.xml ├── draft-ietf-acme-acme.xml ├── rfc8555.edited.xml ├── rfc8555.src-clean.xml └── rfc8555.xml /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | jobs: 3 | build: 4 | docker: 5 | - image: martinthomson/i-d-template:latest 6 | working_directory: ~/draft 7 | 8 | steps: 9 | - checkout 10 | 11 | # Build txt and html versions of drafts 12 | - run: 13 | name: "Build Drafts" 14 | command: "make 'CLONE_ARGS=--reference ~/git-reference'" 15 | 16 | # Update editor's copy on gh-pages 17 | - run: 18 | name: "Update GitHub Pages" 19 | command: | 20 | if [ "${CIRCLE_TAG#draft-}" == "${CIRCLE_TAG}" ]; then 21 | make gh-pages 22 | fi 23 | 24 | # For tagged builds, upload to the datatracker. 25 | - deploy: 26 | name: "Upload to Datatracker" 27 | command: | 28 | if [ "${CIRCLE_TAG#draft-}" != "${CIRCLE_TAG}" ]; then 29 | make upload 30 | fi 31 | 32 | # Save GitHub issues 33 | - run: 34 | name: "Save GitHub Issues" 35 | command: "make issues || make issues DISABLE_ISSUE_FETCH=true && make gh-issues" 36 | 37 | # Create and store artifacts 38 | - run: 39 | name: "Create Artifacts" 40 | command: "make artifacts CI_ARTIFACTS=/tmp/artifacts" 41 | 42 | - store_artifacts: 43 | path: /tmp/artifacts 44 | 45 | 46 | workflows: 47 | version: 2 48 | build: 49 | jobs: 50 | - build: 51 | filters: 52 | tags: 53 | only: /.*?/ 54 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.redxml 2 | *.txt 3 | *.html 4 | *.pdf 5 | *~ 6 | *.swp 7 | /*-[0-9][0-9].xml 8 | .refcache 9 | venv/ 10 | draft-ietf-acme-acme.xml 11 | lib 12 | .targets.mk 13 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | sudo: false 3 | addons: 4 | apt: 5 | packages: 6 | - python-pip 7 | 8 | install: 9 | - gem install kramdown-rfc2629 10 | - pip install xml2rfc 11 | 12 | script: make ghpages 13 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Before submitting feedback, please familiarize yourself with our current issues 4 | list and review the [working group 5 | documents](https://datatracker.ietf.org/wg/acme/documents/) and [mailing 6 | list discussion](https://mailarchive.ietf.org/arch/browse/acme/). If you're 7 | new to this, you may also want to read the [Tao of the 8 | IETF](https://www.ietf.org/tao.html). 9 | 10 | Be aware that all contributions to the specification fall under the "NOTE WELL" 11 | terms outlined below. 12 | 13 | 1. The best way to provide feedback (editorial or design) and ask questions is 14 | sending an e-mail to our mailing list 15 | ([info](https://www.ietf.org/mailman/listinfo/acme)). This will ensure that 16 | the entire Working Group sees your input in a timely fashion. 17 | 18 | 2. If you have **editorial** suggestions (i.e., those that do not change the 19 | meaning of the specification), you can either: 20 | 21 | a) Fork this repository and submit a pull request; this is the lowest 22 | friction way to get editorial changes in. 23 | 24 | b) Submit a new issue to GitHub, and mention that you believe it is editorial 25 | in the issue body. It is not necessary to notify the mailing list for 26 | editorial issues. 27 | 28 | c) Make comments on individual commits in GitHub. Note that this feedback is 29 | processed only with best effort by the editors, so it should only be used for 30 | quick editorial suggestions or questions. 31 | 32 | 3. For non-editorial (i.e., **design**) issues, you can also create an issue on 33 | GitHub. However, you **must notify the mailing list** when creating such issues, 34 | providing a link to the issue in the message body. 35 | 36 | Note that **GitHub issues are not for substantial discussions**; the only 37 | appropriate place to discuss design issues is on the mailing list itself. 38 | 39 | 40 | ## NOTE WELL 41 | 42 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 43 | for publication as all or part of an IETF Internet-Draft or RFC and any 44 | statement made within the context of an IETF activity is considered an "IETF 45 | Contribution". Such statements include oral statements in IETF sessions, as 46 | well as written and electronic communications made at any time or place, which 47 | are addressed to: 48 | 49 | * The IETF plenary session 50 | * The IESG, or any member thereof on behalf of the IESG 51 | * Any IETF mailing list, including the IETF list itself, any working group 52 | or design team list, or any other list functioning under IETF auspices 53 | * Any IETF working group or portion thereof 54 | * Any Birds of a Feather (BOF) session 55 | * The IAB or any member thereof on behalf of the IAB 56 | * The RFC Editor or the Internet-Drafts function 57 | 58 | All IETF Contributions are subject to the rules of 59 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 60 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 61 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 62 | 63 | Statements made outside of an IETF session, mailing list or other function, 64 | that are clearly not intended to be input to an IETF activity, group or 65 | function, are not IETF Contributions in the context of this notice. 66 | 67 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 68 | 3979](https://tools.ietf.org/html/rfc3979) for details. 69 | 70 | A participant in any IETF activity is deemed to accept all IETF rules of 71 | process, as documented in Best Current Practices RFCs and IESG Statements. 72 | 73 | A participant in any IETF activity acknowledges that written, audio and video 74 | records of meetings may be made and may be available to the public. 75 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | LIBDIR := lib 2 | include $(LIBDIR)/main.mk 3 | 4 | $(LIBDIR)/main.mk: 5 | ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) 6 | git submodule sync 7 | git submodule update $(CLONE_ARGS) --init 8 | else 9 | git clone -q --depth 10 $(CLONE_ARGS) \ 10 | -b master https://github.com/martinthomson/i-d-template $(LIBDIR) 11 | endif 12 | 13 | .PHONY: rfced 14 | rfced:: 15 | kramdown-rfc2629 draft-ietf-acme-acme.md >rfced/draft-ietf-acme-acme.xml 16 | cd rfced && python clean-xml.py draft-ietf-acme-acme.clean.xml 17 | -cd rfced && diff -u draft-ietf-acme-acme.clean.xml rfc8555.edited.xml >curr.diff 18 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Automatic Certificate Management Environment (ACME) 2 | 3 | This is the working area for the Working Group internet-draft, "Automatic Certificate Management Environment (ACME)". 4 | 5 | * [Editor's copy](https://ietf-wg-acme.github.io/acme/) 6 | * [Build history](https://circleci.com/gh/ietf-wg-acme/acme) 7 | * [Working Group Draft](https://tools.ietf.org/html/draft-ietf-acme-acme) 8 | 9 | 10 | ## Contributing 11 | 12 | Before submitting feedback, please familiarize yourself with our current issues 13 | list and review the [working group 14 | documents](https://datatracker.ietf.org/wg/acme/documents/) and [mailing 15 | list discussion](https://mailarchive.ietf.org/arch/browse/acme/). If you're 16 | new to this, you may also want to read the [Tao of the 17 | IETF](https://www.ietf.org/tao.html). 18 | 19 | Be aware that all contributions to the specification fall under the "NOTE WELL" 20 | terms outlined below. 21 | 22 | 1. The best way to provide feedback (editorial or design) and ask questions is 23 | sending an e-mail to our mailing list 24 | ([info](https://www.ietf.org/mailman/listinfo/acme)). This will ensure that 25 | the entire Working Group sees your input in a timely fashion. 26 | 27 | 2. If you have **editorial** suggestions (i.e., those that do not change the 28 | meaning of the specification), you can either: 29 | 30 | a) Fork this repository and submit a pull request; this is the lowest 31 | friction way to get editorial changes in. 32 | 33 | b) Submit a new issue to GitHub, and mention that you believe it is editorial 34 | in the issue body. It is not necessary to notify the mailing list for 35 | editorial issues. 36 | 37 | c) Make comments on individual commits in GitHub. Note that this feedback is 38 | processed only with best effort by the editors, so it should only be used for 39 | quick editorial suggestions or questions. 40 | 41 | 3. For non-editorial (i.e., **design**) issues, you can also create an issue on 42 | GitHub. However, you **must notify the mailing list** when creating such issues, 43 | providing a link to the issue in the message body. 44 | 45 | Note that **GitHub issues are not for substantial discussions**; the only 46 | appropriate place to discuss design issues is on the mailing list itself. 47 | 48 | 49 | ## Building the Draft 50 | 51 | Formatted text and HTML versions of the draft can be built using `make`. 52 | 53 | ```sh 54 | $ make 55 | ``` 56 | 57 | This requires that you have the necessary software installed. There are several 58 | other tools that are enabled by make, check the Makefile for details, including 59 | links to the software those tools might require. 60 | 61 | 62 | ## Installation and Setup 63 | 64 | Mac users will need to install 65 | [Xcode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see 66 | [this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. 67 | 68 | Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. 69 | 70 | All systems require [xml2rfc](http://xml2rfc.ietf.org/). This 71 | requires [Python](https://www.python.org/). The easiest way to get 72 | `xml2rfc` is with `pip`. 73 | 74 | Using a `virtualenv`: 75 | 76 | ```sh 77 | $ virtualenv --no-site-packages venv 78 | # remember also to activate the virtualenv before any 'make' run 79 | $ source venv/bin/activate 80 | $ pip install xml2rfc 81 | ``` 82 | 83 | To your local user account: 84 | 85 | ```sh 86 | $ pip install --user xml2rfc 87 | ``` 88 | 89 | Or globally: 90 | 91 | ```sh 92 | $ sudo pip install xml2rfc 93 | ``` 94 | 95 | xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and 96 | [libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and 97 | `libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, 98 | Fedora). 99 | 100 | If you use markdown, you will also need to install `kramdown-rfc2629`, 101 | which requires Ruby and can be installed using the Ruby package 102 | manager, `gem`: 103 | 104 | ```sh 105 | $ gem install kramdown-rfc2629 106 | ``` 107 | 108 | Some other helpful tools are listed in `config.mk`. 109 | 110 | 111 | ## NOTE WELL 112 | 113 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 114 | for publication as all or part of an IETF Internet-Draft or RFC and any 115 | statement made within the context of an IETF activity is considered an "IETF 116 | Contribution". Such statements include oral statements in IETF sessions, as 117 | well as written and electronic communications made at any time or place, which 118 | are addressed to: 119 | 120 | * The IETF plenary session 121 | * The IESG, or any member thereof on behalf of the IESG 122 | * Any IETF mailing list, including the IETF list itself, any working group 123 | or design team list, or any other list functioning under IETF auspices 124 | * Any IETF working group or portion thereof 125 | * Any Birds of a Feather (BOF) session 126 | * The IAB or any member thereof on behalf of the IAB 127 | * The RFC Editor or the Internet-Drafts function 128 | 129 | All IETF Contributions are subject to the rules of 130 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 131 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 132 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 133 | 134 | Statements made outside of an IETF session, mailing list or other function, 135 | that are clearly not intended to be input to an IETF activity, group or 136 | function, are not IETF Contributions in the context of this notice. 137 | 138 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 139 | 3979](https://tools.ietf.org/html/rfc3979) for details. 140 | 141 | A participant in any IETF activity is deemed to accept all IETF rules of 142 | process, as documented in Best Current Practices RFCs and IESG Statements. 143 | 144 | A participant in any IETF activity acknowledges that written, audio and video 145 | records of meetings may be made and may be available to the public. 146 | -------------------------------------------------------------------------------- /SUBMITTING.md: -------------------------------------------------------------------------------- 1 | # Submitting Drafts 2 | 3 | Occasionally, you will want to submit versions of your draft to the official 4 | IETF repository. The following process makes this easy. 5 | 6 | Make a submission version of your draft. The Makefile uses git tags to work out 7 | what version to create. It looks for the last version number you have tagged 8 | the draft with and calculates the next version. When there are no tags, it 9 | generates a `-00` version. 10 | 11 | ```sh 12 | $ make submit 13 | ``` 14 | 15 | [Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) 16 | that this produces. 17 | 18 | Then you can tag your repository and upload the tags. The tag you should 19 | use is your draft name with the usual number in place of `-latest`. 20 | 21 | ```sh 22 | $ git tag draft-ietf-unicorn-protocol-03 23 | $ git push --tags 24 | ``` 25 | -------------------------------------------------------------------------------- /draft-ietf-acme-acme.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Automatic Certificate Management Environment (ACME)" 3 | abbrev: ACME 4 | docname: draft-ietf-acme-acme-latest 5 | category: std 6 | workgroup: ACME Working Group 7 | ipr: trust200902 8 | date: 2019-02 9 | 10 | stand_alone: yes 11 | pi: 12 | toc: yes 13 | sortrefs: yes 14 | symrefs: yes 15 | compact: yes 16 | subcompact: no 17 | 18 | keyword: [certificate, HTTPS, PKI, X.509] 19 | 20 | author: 21 | - 22 | ins: R. Barnes 23 | name: Richard Barnes 24 | org: Cisco 25 | email: rlb@ipv.sx 26 | - 27 | ins: J. Hoffman-Andrews 28 | name: Jacob Hoffman-Andrews 29 | org: EFF 30 | email: jsha@eff.org 31 | - 32 | ins: D. McCarney 33 | name: Daniel McCarney 34 | org: Let's Encrypt 35 | email: cpu@letsencrypt.org 36 | - 37 | ins: J. Kasten 38 | name: James Kasten 39 | org: University of Michigan 40 | email: jdkasten@umich.edu 41 | 42 | informative: 43 | CABFBR: 44 | title: CA/Browser Forum Baseline Requirements 45 | author: 46 | org: CA/Browser Forum 47 | date: 2018-09 48 | target: https://cabforum.org/baseline-requirements-documents/ 49 | normative: 50 | FIPS180-4: 51 | title: NIST FIPS 180-4, Secure Hash Standard 52 | author: 53 | name: NIST 54 | ins: National Institute of Standards and Technology, U.S. Department of Commerce 55 | date: 2012-03 56 | target: http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf 57 | JSS15: 58 | title: On the Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1 v1.5 Encryption 59 | author: 60 | name: Tibor Jager 61 | ins: T. Hager 62 | author: 63 | name: Jörg Schwenk 64 | ins: J. Schwenk 65 | author: 66 | name: Juraj Somorovsky 67 | ins: J. Somorovsky 68 | target: https://dl.acm.org/citation.cfm?id=2813657 69 | REST: 70 | title: Architectural Styles and the Design of Network-based Software Architectures 71 | author: 72 | name: Roy Thomas Fielding 73 | ins: R. Fielding 74 | date: 2000 75 | target: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 76 | 77 | 78 | --- abstract 79 | 80 | Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, 81 | the most significant of which is the authentication of domain names. Thus, 82 | certification authorities (CAs) in the Web PKI are trusted to verify that an applicant 83 | for a certificate legitimately represents the domain name(s) in the certificate. 84 | As of this writing, this verification is done through a collection of ad hoc mechanisms. 85 | This document describes a protocol that a CA and an 86 | applicant can use to automate the process of verification and certificate 87 | issuance. The protocol also provides facilities for other certificate 88 | management functions, such as certificate revocation. 89 | 90 | --- middle 91 | 92 | # Introduction 93 | 94 | Certificates {{!RFC5280}} in the Web PKI are most commonly used to authenticate 95 | domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to 96 | verify that an applicant for a certificate legitimately represents the domain 97 | name(s) in the certificate. 98 | 99 | Different types of certificates reflect different kinds of CA verification of 100 | information about the certificate subject. "Domain Validation" (DV) 101 | certificates are by far the most common type. The only validation 102 | the CA is required to perform in the DV issuance process is to 103 | verify that the requester has effective control of the domain [CABFBR]. The CA is not 104 | required to attempt to verify the requester's 105 | real-world identity. (This is as opposed to "Organization Validation" (OV) and 106 | "Extended Validation" (EV) certificates, where the process is intended to also 107 | verify the real-world identity of the requester.) 108 | 109 | Existing Web PKI certificate authorities tend to use a set of ad hoc 110 | protocols for certificate issuance and identity verification. In the case of DV 111 | certificates, a typical user experience is something like: 112 | 113 | * Generate a PKCS#10 {{!RFC2986}} Certificate Signing Request (CSR). 114 | * Cut and paste the CSR into a CA's web page. 115 | * Prove ownership of the domain(s) in the CSR by one of the following methods: 116 | * Put a CA-provided challenge at a specific place on the web server. 117 | * Put a CA-provided challenge in a DNS record corresponding to the target 118 | domain. 119 | * Receive a CA-provided challenge at (hopefully) an administrator-controlled email 120 | address corresponding to the domain, and then respond to it on the CA's web 121 | page. 122 | * Download the issued certificate and install it on the user's Web Server. 123 | 124 | With the exception of the CSR itself and the certificates that are issued, these 125 | are all completely ad hoc procedures and are accomplished by getting the human 126 | user to follow interactive natural-language instructions from the CA rather than 127 | by machine-implemented published protocols. In many cases, the instructions are 128 | difficult to follow and cause significant frustration and confusion. Informal usability tests 129 | by the authors indicate that webmasters often need 1-3 hours to obtain and 130 | install a certificate for a domain. Even in the best case, the lack of 131 | published, standardized mechanisms presents an obstacle to the wide deployment 132 | of HTTPS and other PKIX-dependent systems because it inhibits mechanization of 133 | tasks related to certificate issuance, deployment, and revocation. 134 | 135 | This document describes an extensible framework for automating the issuance and 136 | domain validation procedure, thereby allowing servers and infrastructure 137 | software to obtain certificates without user interaction. Use of this protocol 138 | should radically simplify the deployment of HTTPS and the practicality of PKIX-based 139 | authentication for other protocols based on Transport Layer Security (TLS) 140 | {{!RFC5246}}. 141 | 142 | It should be noted that while the focus of this document is on validating 143 | domain names for purposes of issuing certificates in the Web PKI, ACME supports 144 | extensions for uses with other identifiers in other PKI contexts. For example, 145 | as of this writing, there is ongoing work to use ACME for issuance of Web PKI 146 | certificates attesting to IP addresses {{?I-D.ietf-acme-ip}} and Secure Telephone Identity Revisited (STIR) 147 | certificates attesting to telephone numbers {{?I-D.ietf-acme-telephone}}. 148 | 149 | ACME can also be used to automate some aspects of certificate management even 150 | where non-automated processes are still needed. For example, the external 151 | account binding feature (see {{external-account-binding}}) can allow an ACME 152 | account to use authorizations that have been granted to an external, non-ACME 153 | account. This allows ACME to address issuance scenarios that cannot yet be 154 | fully automated, such as the issuance of "Extended Validation" certificates. 155 | 156 | 157 | # Deployment Model and Operator Experience 158 | 159 | The guiding use case for ACME is obtaining certificates for websites 160 | (HTTPS {{!RFC2818}}). In this case, a web server is intended to speak 161 | for one or more domains, and the process of certificate issuance is intended to 162 | verify that this web server actually speaks for the domain(s). 163 | 164 | DV certificate validation commonly checks claims about properties related to 165 | control of a domain name -- properties that can be observed by the certificate 166 | issuer in an interactive process that can be conducted purely online. That 167 | means that under typical circumstances, all steps in the request, verification, 168 | and issuance process can be represented and performed by Internet protocols with 169 | no out-of-band human intervention. 170 | 171 | Prior to ACME, when deploying an HTTPS server, a server operator typically gets a 172 | prompt to generate a self-signed certificate. If the operator were instead 173 | deploying an HTTPS server using ACME, the experience would be something like this: 174 | 175 | * The operator's ACME client prompts the operator for the intended domain name(s) that the 176 | web server is to stand for. 177 | * The ACME client presents the operator with a list of CAs from which it could 178 | get a certificate. (This list will change over time based on the capabilities 179 | of CAs and updates to ACME configuration.) The ACME client might prompt the 180 | operator for payment information at this point. 181 | * The operator selects a CA. 182 | * In the background, the ACME client contacts the CA and requests that it 183 | issue a certificate for the intended domain name(s). 184 | * The CA verifies that the client controls the requested domain name(s) by 185 | having the ACME client perform some action(s) that can only be done 186 | with control of the domain name(s). 187 | For example, the CA might require a client requesting example.com 188 | to provision a DNS record under example.com or an HTTP resource 189 | under http://example.com. 190 | * Once the CA is satisfied, it issues the certificate and the ACME client 191 | automatically downloads and installs it, potentially notifying the operator 192 | via email, SMS, etc. 193 | * The ACME client periodically contacts the CA to get updated certificates, 194 | stapled Online Certificate Status Protocol (OCSP) responses {{?RFC6960}}, or whatever else would be required to keep the web server functional and its credentials up to date. 195 | 196 | In this way, it would be nearly as easy to deploy with a CA-issued certificate 197 | as with a self-signed certificate. Furthermore, the maintenance of that 198 | CA-issued certificate would require minimal manual intervention. Such close 199 | integration of ACME with HTTPS servers allows the immediate and automated 200 | deployment of certificates as they are issued, sparing the human administrator 201 | from much of the time-consuming work described in the previous section. 202 | 203 | 204 | # Terminology 205 | 206 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 208 | "OPTIONAL" in this document are to be interpreted as described in BCP 209 | 14 {{!RFC2119}} {{!RFC8174}} when, and only when, they appear in all 210 | capitals, as shown here. 211 | 212 | The two main roles in ACME are "client" and "server". The ACME client uses the 213 | protocol to request certificate management actions, such as issuance or 214 | revocation. An ACME client may run on a web server, mail server, or some other 215 | server system that requires valid X.509 certificates. Or, it may run on a separate 216 | server that does not consume the certificate but is authorized to respond to a 217 | CA-provided challenge. The ACME server runs at a certification authority 218 | and responds to client requests, performing the requested actions if the client is 219 | authorized. 220 | 221 | An ACME client authenticates to the server by means of an "account key pair". The client uses the 222 | private key of this key pair to sign all messages sent to the server. The 223 | server uses the public key to verify the authenticity and integrity of messages 224 | from the client. 225 | 226 | # Protocol Overview 227 | 228 | ACME allows a client to request certificate management actions using a set of 229 | JavaScript Object Notation (JSON) messages {{!RFC8259}} carried over HTTPS {{!RFC2818}}. 230 | Issuance using ACME resembles a traditional CA's issuance process, in which a user creates an account, 231 | requests a certificate, and proves control of the domain(s) in that certificate in 232 | order for the CA to issue the requested certificate. 233 | 234 | The first phase of ACME is for the client to request an account with the 235 | ACME server. The client generates an asymmetric key pair and requests a 236 | new account, optionally providing contact information, agreeing to terms 237 | of service (ToS), and/or associating the account with an existing account 238 | in another system. The creation request is signed with the generated 239 | private key to prove that the client controls it. 240 | 241 | ~~~~~~~~~~ 242 | Client Server 243 | 244 | [Contact Information] 245 | [ToS Agreement] 246 | [Additional Data] 247 | Signature -------> 248 | Account URL 249 | <------- Account Object 250 | 251 | 252 | [] Information covered by request signatures 253 | ~~~~~~~~~~ 254 | {: title="Account Creation"} 255 | 256 | 257 | Once an account is registered, there are four major steps the client needs to take to 258 | get a certificate: 259 | 260 | 1. Submit an order for a certificate to be issued 261 | 2. Prove control of any identifiers requested in the certificate 262 | 3. Finalize the order by submitting a CSR 263 | 4. Await issuance and download the issued certificate 264 | 265 | The client's order for a certificate describes the desired identifiers 266 | plus a few additional fields that 267 | capture semantics that are not supported in the CSR format. If the server is 268 | willing to consider issuing such a certificate, it responds with a list of 269 | requirements that the client must satisfy before the certificate will be issued. 270 | 271 | For example, in most cases, the server will require the client to demonstrate 272 | that it controls the identifiers in the requested certificate. Because there 273 | are many different ways to validate possession of different types of 274 | identifiers, the server will choose from an extensible set of challenges that 275 | are appropriate for the identifier being claimed. The client responds with a 276 | set of responses that tell the server which challenges the client has completed. 277 | The server then validates that the client has completed the challenges. 278 | 279 | Once the validation process is complete and the server is satisfied that the 280 | client has met its requirements, the client finalizes the order by submitting 281 | a PKCS#10 Certificate Signing Request (CSR). The server will issue the requested 282 | certificate and make it available to the client. 283 | 284 | ~~~~~~~~~~ 285 | Client Server 286 | 287 | [Order] 288 | Signature -------> 289 | <------- Required Authorizations 290 | 291 | [Responses] 292 | Signature -------> 293 | 294 | <~~~~~~~~Validation~~~~~~~~> 295 | 296 | [CSR] 297 | Signature -------> 298 | <------- Acknowledgement 299 | 300 | <~~~~~~Await issuance~~~~~~> 301 | 302 | [POST-as-GET request] 303 | Signature -------> 304 | <------- Certificate 305 | 306 | [] Information covered by request signatures 307 | ~~~~~~~~~~ 308 | {: title="Certificate Issuance"} 309 | 310 | To revoke a certificate, the client sends a signed revocation request indicating 311 | the certificate to be revoked: 312 | 313 | ~~~~~~~~~~ 314 | Client Server 315 | 316 | [Revocation request] 317 | Signature --------> 318 | 319 | <-------- Result 320 | 321 | [] Information covered by request signatures 322 | ~~~~~~~~~~ 323 | {: title="Certificate Revocation"} 324 | 325 | Note that while ACME is defined with enough flexibility to handle different 326 | types of identifiers in principle, the primary use case addressed by this 327 | document is the case where domain names are used as identifiers. For example, 328 | all of the identifier validation challenges described in 329 | {{identifier-validation-challenges}} address validation of domain names. 330 | The use of ACME for other identifiers will require further specification in order 331 | to describe how these identifiers are encoded in the protocol and what types of 332 | validation challenges the server might require. 333 | 334 | # Character Encoding 335 | 336 | All requests and responses sent via HTTP by ACME clients, ACME servers, and 337 | validation servers as well as any inputs for digest computations MUST be encoded 338 | using the UTF-8 character set {{!RFC3629}}. Note that identifiers that appear in 339 | certificates may have their own encoding considerations (e.g., DNS names containing 340 | non-ASCII characters are expressed as A-labels rather than U-labels). Any such 341 | encoding considerations are to be applied prior to the aforementioned UTF-8 342 | encoding. 343 | 344 | # Message Transport 345 | 346 | Communications between an ACME client and an ACME server are done over HTTPS, 347 | using JSON Web Signature (JWS) {{!RFC7515}} to provide some additional security 348 | properties for messages sent from 349 | the client to the server. HTTPS provides server authentication and 350 | confidentiality. With some ACME-specific extensions, JWS provides 351 | authentication of the client's request payloads, anti-replay protection, and 352 | integrity for the HTTPS request URL. 353 | 354 | ## HTTPS Requests 355 | 356 | Each ACME function is accomplished by the client sending a sequence of HTTPS 357 | requests to the server {{!RFC2818}}, carrying JSON messages {{!RFC8259}}. Use of 358 | HTTPS is REQUIRED. Each subsection of 359 | {{certificate-management}} below describes the message formats used by the 360 | function and the order in which messages are sent. 361 | 362 | In most HTTPS transactions used by ACME, the ACME client is the HTTPS client 363 | and the ACME server is the HTTPS server. The ACME server acts as a 364 | client when validating challenges: an HTTP client when 365 | validating an 'http-01' challenge, a DNS client with 'dns-01', etc. 366 | 367 | ACME servers SHOULD follow the recommendations of {{?RFC7525}} when configuring 368 | their TLS implementations. ACME servers that support TLS 1.3 MAY allow clients 369 | to send early data (0-RTT). This is safe because the ACME protocol itself 370 | includes anti-replay protections (see {{replay-protection}}) in all cases where 371 | they are required. For this reason, there are no restrictions on what ACME 372 | data can be carried in 0-RTT. 373 | 374 | ACME clients MUST send a User-Agent header field, in accordance with 375 | {{!RFC7231}}. This header field SHOULD include the name and version of the 376 | ACME software in addition to the name and version of the underlying 377 | HTTP client software. 378 | 379 | ACME clients SHOULD send an Accept-Language header field in accordance with 380 | {{!RFC7231}} to enable localization of error messages. 381 | 382 | ACME servers that are intended to be generally accessible need to use 383 | Cross-Origin Resource Sharing (CORS) in order to be accessible from 384 | browser-based clients {{?W3C.REC-cors-20140116}}. Such servers SHOULD set the 385 | Access-Control-Allow-Origin header field to the value "\*". 386 | 387 | Binary fields in the JSON objects used by ACME are encoded using base64url 388 | encoding described in Section 5 of {{!RFC4648}} according to the profile specified 389 | in JSON Web Signature in Section 2 of {{!RFC7515}}. This encoding uses a URL safe 390 | character set. Trailing '=' characters MUST be stripped. Encoded 391 | values that include trailing '=' characters MUST be rejected as 392 | improperly encoded. 393 | 394 | ## Request Authentication 395 | 396 | All ACME requests with a non-empty body MUST encapsulate their payload 397 | in a JSON Web Signature (JWS) {{!RFC7515}} object, signed using the account's 398 | private key unless otherwise specified. The server MUST verify the JWS before 399 | processing the request. Encapsulating request bodies in JWS provides 400 | authentication of requests. 401 | 402 | A JWS object sent as the body of an ACME request MUST meet the following additional criteria: 403 | 404 | * The JWS MUST be in the Flattened JSON Serialization {{!RFC7515}} 405 | * The JWS MUST NOT have multiple signatures 406 | * The JWS Unencoded Payload Option {{!RFC7797}} MUST NOT be used 407 | * The JWS Unprotected Header {{!RFC7515}} MUST NOT be used 408 | * The JWS Payload MUST NOT be detached 409 | * The JWS Protected Header MUST include the following fields: 410 | * "alg" (Algorithm) 411 | * This field MUST NOT contain "none" or a Message Authentication Code (MAC) algorithm (e.g. one in which the algorithm registry description mentions MAC/HMAC). 412 | * "nonce" (defined in {{replay-protection}}) 413 | * "url" (defined in {{request-url-integrity}}) 414 | * Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified below 415 | 416 | An ACME server MUST implement the "ES256" signature algorithm {{!RFC7518}} and SHOULD implement the "EdDSA" signature algorithm using the "Ed25519" variant (indicated by "crv") {{!RFC8037}}. 417 | 418 | The "jwk" and "kid" fields are mutually exclusive. Servers MUST reject requests 419 | that contain both. 420 | 421 | For newAccount requests, and for revokeCert requests authenticated by a certificate 422 | key, there MUST be a "jwk" field. This field MUST contain the public key 423 | corresponding to the private key used to sign the JWS. 424 | 425 | For all other requests, the request is signed using an existing account, and 426 | there MUST be a "kid" field. This field MUST contain the account URL received by 427 | POSTing to the newAccount resource. 428 | 429 | If the client sends a JWS signed with an algorithm that the server does not 430 | support, then the server MUST return an error with status code 400 (Bad Request) 431 | and type "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem 432 | document returned with the error MUST include an "algorithms" field with an 433 | array of supported "alg" values. See {{errors}} for more details on 434 | the structure of error responses. 435 | 436 | If the server supports the signature algorithm "alg" but either does not support 437 | or chooses to reject the public key "jwk", then the server MUST return an error 438 | with status code 400 (Bad Request) and type 439 | "urn:ietf:params:acme:error:badPublicKey". The problem document detail SHOULD 440 | describe the reason for rejecting the public key; some example reasons are: 441 | 442 | * "alg" is "RS256" but the modulus "n" is too small (e.g., 512-bit) 443 | * "alg" is "ES256" but "jwk" does not contain a valid P-256 public key 444 | * "alg" is "EdDSA" and "crv" is "Ed448", but the server only supports "EdDSA" 445 | with "Ed25519" 446 | * the corresponding private key is known to have been compromised 447 | 448 | Because client requests in ACME carry JWS objects in the Flattened 449 | JSON Serialization, they must have the Content-Type header field 450 | set to "application/jose+json". If a request does not meet this 451 | requirement, then the server MUST return a response with status code 452 | 415 (Unsupported Media Type). 453 | 454 | ## GET and POST-as-GET Requests {#post-as-get} 455 | 456 | Note that authentication via signed JWS request bodies implies that 457 | requests without an entity body are not authenticated, in particular 458 | GET requests. Except for the cases described in this section, if 459 | the server receives a GET request, it MUST return an error with 460 | status code 405 (Method Not Allowed) and type "malformed". 461 | 462 | If a client wishes to fetch a resource from the server (which would 463 | otherwise be done with a GET), then it MUST send a POST request with 464 | a JWS body as described above, where the payload of the JWS is a 465 | zero-length octet string. In other words, the "payload" field of the 466 | JWS object MUST be present and set to the empty string (""). 467 | 468 | We will refer to these as "POST-as-GET" requests. On receiving a 469 | request with a zero-length (and thus non-JSON) payload, the server 470 | MUST authenticate the sender and verify any access control rules. 471 | Otherwise, the server MUST treat this request as having the same 472 | semantics as a GET request for the same resource. 473 | 474 | The server MUST allow GET requests for the directory and newNonce 475 | resources (see {{resources}}), in addition to POST-as-GET requests 476 | for these resources. This enables clients to bootstrap into the 477 | ACME authentication system. 478 | 479 | ## Request URL Integrity 480 | 481 | It is common in deployment for the entity terminating TLS for HTTPS to be different 482 | from the entity operating the logical HTTPS server, with a "request routing" 483 | layer in the middle. For example, an ACME CA might have a content delivery 484 | network terminate TLS connections from clients so that it can inspect client 485 | requests for denial-of-service (DoS) protection. 486 | 487 | These intermediaries can also change values in the request that are not signed 488 | in the HTTPS request, e.g., the request URL and header fields. ACME uses JWS to 489 | provide an integrity mechanism, which protects against an intermediary 490 | changing the request URL to another ACME URL. 491 | 492 | As noted in {{request-authentication}}, all ACME request objects carry a 493 | "url" header parameter in their protected header. This header parameter encodes 494 | the URL to which the client is directing the request. On receiving such an 495 | object in an HTTP request, the server MUST compare the "url" header parameter to 496 | the request URL. If the two do not match, then the server MUST reject the 497 | request as unauthorized. 498 | 499 | Except for the directory resource, all ACME resources are addressed with URLs 500 | provided to the client by the server. In POST requests sent to these resources, the client MUST set 501 | the "url" header parameter to the exact string provided by the server (rather 502 | than performing any re-encoding on the URL). The server SHOULD perform the 503 | corresponding string equality check, configuring each resource with the URL 504 | string provided to clients and having the resource check that requests have the 505 | same string in their "url" header parameter. The server MUST reject the request 506 | as unauthorized if the string equality check fails. 507 | 508 | ### "url" (URL) JWS Header Parameter {#url-url-jws-header-parameter} 509 | 510 | The "url" header parameter specifies the URL {{!RFC3986}} to which this JWS 511 | object is directed. The "url" header parameter MUST be carried in the protected 512 | header of the JWS. The value of the "url" header parameter MUST be a string 513 | representing the target URL. 514 | 515 | ## Replay Protection 516 | 517 | In order to protect ACME resources from any possible replay attacks, ACME 518 | POST requests have a mandatory anti-replay mechanism. This mechanism is based on the 519 | server maintaining a list of nonces that it has issued, and requiring 520 | any signed request from the client to carry such a nonce. 521 | 522 | An ACME server provides nonces to clients using the HTTP Replay-Nonce header field, 523 | as specified in {{replay-nonce}}. The server MUST include a Replay-Nonce 524 | header field in every successful response to a POST request and SHOULD provide 525 | it in error responses as well. 526 | 527 | Every JWS sent by an ACME client MUST include, in its protected header, the 528 | "nonce" header parameter, with contents as defined in 529 | {{nonce-nonce-jws-header-parameter}}. As part of JWS verification, the 530 | ACME server MUST verify that the value of the "nonce" header is a value that the 531 | server previously provided in a Replay-Nonce header field. Once a nonce value 532 | has appeared in an ACME request, the server MUST consider it invalid, in the same 533 | way as a value it had never issued. 534 | 535 | When a server rejects a request because its nonce value was unacceptable (or not 536 | present), it MUST provide HTTP status code 400 (Bad Request), and indicate the 537 | ACME error type "urn:ietf:params:acme:error:badNonce". An error response with 538 | the "badNonce" error type MUST include a Replay-Nonce header field with a 539 | fresh nonce that the server will accept in a retry of the original 540 | query (and possibly in other requests, according to the server's 541 | nonce scoping policy). 542 | On receiving such a response, a client SHOULD retry the request using the new 543 | nonce. 544 | 545 | The precise method used to generate and track nonces is up to the server. For 546 | example, the server could generate a random 128-bit value for each response, 547 | keep a list of issued nonces, and strike nonces from this list as they are used. 548 | 549 | Other than the constraint above with regard to nonces issued in 550 | "badNonce" responses, ACME does not constrain how servers 551 | scope nonces. Clients MAY assume that nonces have broad scope, 552 | e.g., by having a single pool of nonces used for all requests. 553 | However, when retrying in response to a "badNonce" error, the client 554 | MUST use the nonce provided in the error response. Servers should 555 | scope nonces broadly enough that retries are not needed very often. 556 | 557 | ### Replay-Nonce 558 | 559 | The Replay-Nonce HTTP header field includes a server-generated value that the 560 | server can use to detect unauthorized replay in future client requests. The 561 | server MUST generate the values provided in Replay-Nonce header fields in such a way that 562 | they are unique to each message, with high probability, and unpredictable to anyone besides the server. For instance, it is 563 | acceptable to generate Replay-Nonces randomly. 564 | 565 | The value of the Replay-Nonce header field MUST be an octet string encoded according to 566 | the base64url encoding described in Section 2 of {{!RFC7515}}. Clients MUST 567 | ignore invalid Replay-Nonce values. The ABNF {{!RFC5234}} for the Replay-Nonce 568 | header field follows: 569 | 570 | ~~~~~ 571 | base64url = ALPHA / DIGIT / "-" / "_" 572 | 573 | Replay-Nonce = 1*base64url 574 | ~~~~~ 575 | 576 | The Replay-Nonce header field SHOULD NOT be included in HTTP request messages. 577 | 578 | ### "nonce" (Nonce) JWS Header Parameter {#nonce-nonce-jws-header-parameter} 579 | 580 | The "nonce" header parameter provides a unique value that enables the verifier 581 | of a JWS to recognize when replay has occurred. The "nonce" header parameter 582 | MUST be carried in the protected header of the JWS. 583 | 584 | The value of the "nonce" header parameter MUST be an octet string, encoded 585 | according to the base64url encoding described in Section 2 of {{!RFC7515}}. If 586 | the value of a "nonce" header parameter is not valid according to this encoding, 587 | then the verifier MUST reject the JWS as malformed. 588 | 589 | ## Rate Limits 590 | 591 | Creation of resources can be rate limited by ACME servers to ensure fair usage and 592 | prevent abuse. Once the rate limit is exceeded, the server MUST respond 593 | with an error with the type "urn:ietf:params:acme:error:rateLimited". 594 | Additionally, the server SHOULD send a Retry-After header field {{!RFC7231}} indicating 595 | when the current request may succeed again. If multiple rate limits are 596 | in place, that is the time where all rate limits allow access again for 597 | the current request with exactly the same parameters. 598 | 599 | In addition to the human-readable "detail" field of the error response, the 600 | server MAY send one or multiple link relations in the Link header field {{!RFC8288}} pointing to 601 | documentation about the specific rate limit that was hit, using the "help" link relation type. 602 | 603 | ## Errors 604 | 605 | Errors can be reported in ACME both at the HTTP layer and within challenge 606 | objects as defined in {{identifier-validation-challenges}}. ACME servers can 607 | return responses with an HTTP error response code (4XX or 5XX). For example, 608 | if the client submits a request using a method not allowed in this document, 609 | then the server MAY return status code 405 (Method Not Allowed). 610 | 611 | When the server responds with an error status, it SHOULD provide additional 612 | information using a problem document {{!RFC7807}}. To facilitate automatic 613 | response to errors, this document defines the following standard tokens for use 614 | in the "type" field (within the ACME URN namespace "urn:ietf:params:acme:error:"): 615 | 616 | | Type | Description | 617 | |:------------------------|:---------------------------------------------------------------------------------------------| 618 | | accountDoesNotExist | The request specified an account that does not exist | 619 | | alreadyRevoked | The request specified a certificate to be revoked that has already been revoked | 620 | | badCSR | The CSR is unacceptable (e.g., due to a short key) | 621 | | badNonce | The client sent an unacceptable anti-replay nonce | 622 | | badPublicKey | The JWS was signed by a public key the server does not support | 623 | | badRevocationReason | The revocation reason provided is not allowed by the server | 624 | | badSignatureAlgorithm | The JWS was signed with an algorithm the server does not support | 625 | | caa | Certification Authority Authorization (CAA) records forbid the CA from issuing a certificate | 626 | | compound | Specific error conditions are indicated in the "subproblems" array. | 627 | | connection | The server could not connect to validation target | 628 | | dns | There was a problem with a DNS query during identifier validation | 629 | | externalAccountRequired | The request must include a value for the "externalAccountBinding" field | 630 | | incorrectResponse | Response received didn't match the challenge's requirements | 631 | | invalidContact | A contact URL for an account was invalid | 632 | | malformed | The request message was malformed | 633 | | orderNotReady | The request attempted to finalize an order that is not ready to be finalized | 634 | | rateLimited | The request exceeds a rate limit | 635 | | rejectedIdentifier | The server will not issue certificates for the identifier | 636 | | serverInternal | The server experienced an internal error | 637 | | tls | The server received a TLS error during validation | 638 | | unauthorized | The client lacks sufficient authorization | 639 | | unsupportedContact | A contact URL for an account used an unsupported protocol scheme | 640 | | unsupportedIdentifier | An identifier is of an unsupported type | 641 | | userActionRequired | Visit the "instance" URL and take actions specified there | 642 | 643 | This list is not exhaustive. The server MAY return errors whose "type" field is 644 | set to a URI other than those defined above. Servers MUST NOT use the ACME URN 645 | namespace for errors not listed in the appropriate IANA registry (see {{acme-urn-space}}). Clients SHOULD display the 646 | "detail" field of all errors. 647 | 648 | In the remainder of this document, we use the tokens in the table above to refer 649 | to error types, rather than the full URNs. For example, an "error of type 650 | 'badCSR'" refers to an error document with "type" value 651 | "urn:ietf:params:acme:error:badCSR". 652 | 653 | ### Subproblems {#subproblems} 654 | 655 | Sometimes a CA may need to return multiple errors in response to a request. 656 | Additionally, the CA may need to attribute errors to specific 657 | identifiers. For instance, a newOrder request may contain multiple 658 | identifiers for which the CA cannot issue. In this situation, an ACME 659 | problem document MAY contain the "subproblems" field, containing a JSON 660 | array of problem documents, each of which MAY contain an "identifier" 661 | field. If present, the "identifier" field MUST contain an ACME identifier 662 | ({{iana-identifier}}). The "identifier" field MUST NOT be present at 663 | the top level in ACME problem documents. It can only be present in subproblems. 664 | Subproblems need not all have the same type, and they do not need to match the top level type. 665 | 666 | ACME clients may choose to use the "identifier" field of a subproblem 667 | as a hint that an operation would succeed if that identifier were omitted. For 668 | instance, if an order contains ten DNS identifiers, and the newOrder 669 | request returns a problem document with two subproblems (referencing two 670 | of those identifiers), the ACME client may choose to submit another order 671 | containing only the eight identifiers not listed in the problem document. 672 | 673 | ~~~~~ 674 | HTTP/1.1 403 Forbidden 675 | Content-Type: application/problem+json 676 | Link: ;rel="index" 677 | 678 | { 679 | "type": "urn:ietf:params:acme:error:malformed", 680 | "detail": "Some of the identifiers requested were rejected", 681 | "subproblems": [ 682 | { 683 | "type": "urn:ietf:params:acme:error:malformed", 684 | "detail": "Invalid underscore in DNS name \"_example.org\"", 685 | "identifier": { 686 | "type": "dns", 687 | "value": "_example.org" 688 | } 689 | }, 690 | { 691 | "type": "urn:ietf:params:acme:error:rejectedIdentifier", 692 | "detail": "This CA will not issue for \"example.net\"", 693 | "identifier": { 694 | "type": "dns", 695 | "value": "example.net" 696 | } 697 | } 698 | ] 699 | } 700 | ~~~~~ 701 | 702 | # Certificate Management 703 | 704 | In this section, we describe the certificate management functions that ACME 705 | enables: 706 | 707 | * Account Creation 708 | * Ordering a Certificate 709 | * Identifier Authorization 710 | * Certificate Issuance 711 | * Certificate Revocation 712 | 713 | ## Resources 714 | 715 | ACME is structured as a HTTP-based application with the following types of resources: 716 | 717 | * Account resources, representing information about an account 718 | ({{account-objects}}, {{account-management}}) 719 | * Order resources, representing an account's requests to issue certificates 720 | ({{order-objects}}) 721 | * Authorization resources, representing an account's authorization to act for an 722 | identifier ({{authorization-objects}}) 723 | * Challenge resources, representing a challenge to prove control of an 724 | identifier ({{identifier-authorization}}, {{identifier-validation-challenges}}) 725 | * Certificate resources, representing issued certificates 726 | ({{downloading-the-certificate}}) 727 | * A "directory" resource ({{directory}}) 728 | * A "newNonce" resource ({{getting-a-nonce}}) 729 | * A "newAccount" resource ({{account-management}}) 730 | * A "newOrder" resource ({{applying-for-certificate-issuance}}) 731 | * A "revokeCert" resource ({{certificate-revocation}}) 732 | * A "keyChange" resource ({{account-key-roll-over}}) 733 | 734 | The server MUST provide "directory" and "newNonce" resources. 735 | 736 | ACME uses different URLs for different management functions. Each function is 737 | listed in a directory along with its corresponding URL, so clients only need to 738 | be configured with the directory URL. These URLs are connected by a few 739 | different link relations {{!RFC5988}}. 740 | 741 | The "up" link relation is used with challenge resources to indicate the 742 | authorization resource to which a challenge belongs. It is also used, with some 743 | media types, from certificate resources to indicate a resource from which the 744 | client may fetch a chain of CA certificates that could be used to validate the 745 | certificate in the original resource. 746 | 747 | The "index" link relation is present on all resources other than the 748 | directory and indicates the URL of the directory. 749 | 750 | The following diagram illustrates the relations between resources on an ACME 751 | server. For the most part, these relations are expressed by URLs provided as 752 | strings in the resources' JSON representations. Lines with labels in quotes 753 | indicate HTTP link relations. 754 | 755 | ~~~~~~~~~~ 756 | directory 757 | | 758 | +--> newNonce 759 | | 760 | +----------+----------+-----+-----+------------+ 761 | | | | | | 762 | | | | | | 763 | V V V V V 764 | newAccount newAuthz newOrder revokeCert keyChange 765 | | | | 766 | | | | 767 | V | V 768 | account | order --+--> finalize 769 | | | | 770 | | | +--> cert 771 | | V 772 | +---> authorization 773 | | ^ 774 | | | "up" 775 | V | 776 | challenge 777 | ~~~~~~~~~~ 778 | {: title="ACME Resources and Relationships"} 779 | 780 | The following table illustrates a typical sequence of requests required to 781 | establish a new account with the server, prove control of an identifier, issue a 782 | certificate, and fetch an updated certificate some time after issuance. The 783 | "->" is a mnemonic for a Location header field pointing to a created resource. 784 | 785 | | Action | Request | Response | 786 | |:----------------------|:-----------------------------------------|:---------------| 787 | | Get directory | GET directory | 200 | 788 | | Get nonce | HEAD newNonce | 200 | 789 | | Create account | POST newAccount | 201 -> account | 790 | | Submit order | POST newOrder | 201 -> order | 791 | | Fetch challenges | POST-as-GET order's authorization urls | 200 | 792 | | Respond to challenges | POST authorization challenge urls | 200 | 793 | | Poll for status | POST-as-GET order | 200 | 794 | | Finalize order | POST order's finalize url | 200 | 795 | | Poll for status | POST-as-GET order | 200 | 796 | | Download certificate | POST-as-GET order's certificate url | 200 | 797 | 798 | The remainder of this section provides the details of how these resources are 799 | structured and how the ACME protocol makes use of them. 800 | 801 | ### Directory 802 | 803 | In order to help clients configure themselves with the right URLs for each ACME 804 | operation, ACME servers provide a directory object. This should be the only URL 805 | needed to configure clients. It is a JSON object, whose field names are drawn from 806 | the resource registry ({{iana-resource}}) and whose values are the corresponding 807 | URLs. 808 | 809 | | Field | URL in Value | 810 | |:---------------|:---------------------| 811 | | newNonce | New nonce | 812 | | newAccount | New account | 813 | | newOrder | New order | 814 | | newAuthz | New authorization | 815 | | revokeCert | Revoke certificate | 816 | | keyChange | Key change | 817 | 818 | There is no constraint on the URL of the directory except that it 819 | should be different from the other ACME server resources' URLs, and that it 820 | should not clash with other services. For instance: 821 | 822 | * a host that functions as both an ACME and a Web server may want to keep 823 | the root path "/" for an HTML "front page" and place the ACME 824 | directory under the path "/acme". 825 | 826 | * a host that only functions as an ACME server could place the directory 827 | under the path "/". 828 | 829 | If the ACME server does not implement pre-authorization ({{pre-authorization}}), it 830 | MUST omit the "newAuthz" field of the directory. 831 | 832 | The object MAY additionally contain a "meta" field. If present, it MUST be a 833 | JSON object; each field in the object is an item of metadata relating to 834 | the service provided by the ACME server. 835 | 836 | The following metadata items are defined ({{iana-meta}}), all of which are OPTIONAL: 837 | 838 | termsOfService (optional, string): 839 | : A URL identifying the current terms of service. 840 | 841 | website (optional, string): 842 | : An HTTP or HTTPS URL locating a website providing more 843 | information about the ACME server. 844 | 845 | caaIdentities (optional, array of string): 846 | : The hostnames that the ACME server recognizes as referring to 847 | itself for the purposes of CAA record validation as defined in 848 | {{!RFC6844}}. Each string MUST represent the same sequence of ASCII 849 | code points that the server will expect to see as the "Issuer Domain 850 | Name" in a CAA issue or issuewild property tag. This allows clients 851 | to determine the correct issuer domain name to use when configuring 852 | CAA records. 853 | 854 | externalAccountRequired (optional, boolean): 855 | : If this field is present and set to "true", then the CA requires that all 856 | newAccount requests include an "externalAccountBinding" field associating the 857 | new account with an external account. 858 | 859 | Clients access the directory by sending a GET request to the directory URL. 860 | 861 | ~~~~~~~~~~ 862 | HTTP/1.1 200 OK 863 | Content-Type: application/json 864 | 865 | { 866 | "newNonce": "https://example.com/acme/new-nonce", 867 | "newAccount": "https://example.com/acme/new-account", 868 | "newOrder": "https://example.com/acme/new-order", 869 | "newAuthz": "https://example.com/acme/new-authz", 870 | "revokeCert": "https://example.com/acme/revoke-cert", 871 | "keyChange": "https://example.com/acme/key-change", 872 | "meta": { 873 | "termsOfService": "https://example.com/acme/terms/2017-5-30", 874 | "website": "https://www.example.com/", 875 | "caaIdentities": ["example.com"], 876 | "externalAccountRequired": false 877 | } 878 | } 879 | ~~~~~~~~~~ 880 | 881 | ### Account Objects 882 | 883 | An ACME account resource represents a set of metadata associated with an account. 884 | Account resources have the following structure: 885 | 886 | status (required, string): 887 | : The status of this account. Possible values are "valid", "deactivated", and 888 | "revoked". The value "deactivated" should be used to indicate client-initiated 889 | deactivation whereas "revoked" should be used to indicate server-initiated 890 | deactivation. See {{status-changes}}. 891 | 892 | contact (optional, array of string): 893 | : An array of URLs that the server can use to contact the client for issues 894 | related to this account. For example, the server may wish to notify the 895 | client about server-initiated revocation or certificate expiration. 896 | For information on supported URL schemes, see {{account-management}}. 897 | 898 | termsOfServiceAgreed (optional, boolean): 899 | : Including this field in a newAccount request, with a value of true, indicates 900 | the client's agreement with the terms of service. This field cannot be updated 901 | by the client. 902 | 903 | externalAccountBinding (optional, object): 904 | : Including this field in a newAccount request indicates approval by the holder 905 | of an existing non-ACME account to bind that account to this ACME account. This 906 | field is not updateable by the client (see {{external-account-binding}}). 907 | 908 | orders (required, string): 909 | : A URL from which a list of orders submitted by this account can be fetched via 910 | a POST-as-GET request, as described in {{orders-list}}. 911 | 912 | ~~~~~~~~~~ 913 | { 914 | "status": "valid", 915 | "contact": [ 916 | "mailto:cert-admin@example.org", 917 | "mailto:admin@example.org" 918 | ], 919 | "termsOfServiceAgreed": true, 920 | "orders": "https://example.com/acme/orders/rzGoeA" 921 | } 922 | ~~~~~~~~~~ 923 | 924 | #### Orders List 925 | 926 | Each account object includes an "orders" URL from which a list of orders created 927 | by the account can be fetched via POST-as-GET request. The result of the request 928 | MUST be a JSON object whose "orders" field is an array of URLs, each identifying 929 | an order belonging to the account. The server SHOULD include pending orders 930 | and SHOULD NOT include orders that are invalid in the array of URLs. The server 931 | MAY return an incomplete list, along with a Link header field with a "next" link 932 | relation indicating where further entries can be acquired. 933 | 934 | ~~~~~~~~~~ 935 | HTTP/1.1 200 OK 936 | Content-Type: application/json 937 | Link: ;rel="index" 938 | Link: ;rel="next" 939 | 940 | { 941 | "orders": [ 942 | "https://example.com/acme/order/TOlocE8rfgo", 943 | "https://example.com/acme/order/4E16bbL5iSw", 944 | /* more URLs not shown for example brevity */ 945 | "https://example.com/acme/order/neBHYLfw0mg" 946 | ] 947 | } 948 | ~~~~~~~~~~ 949 | 950 | ### Order Objects 951 | 952 | An ACME order object represents a client's request for a certificate and is 953 | used to track the progress of that order through to issuance. Thus, the object 954 | contains information about the requested certificate, the authorizations that 955 | the server requires the client to complete, and any certificates that have 956 | resulted from this order. 957 | 958 | status (required, string): 959 | : The status of this order. Possible values are "pending", 960 | "ready", "processing", "valid", and "invalid". See 961 | {{status-changes}}. 962 | 963 | expires (optional, string): 964 | : The timestamp after which the server will consider this order invalid, encoded 965 | in the format specified in {{!RFC3339}}. This field is REQUIRED for 966 | objects with "pending" or "valid" in the status field. 967 | 968 | identifiers (required, array of object): 969 | : An array of identifier objects that the order pertains to. 970 | 971 | type (required, string): 972 | : The type of identifier. This document defines the "dns" 973 | identifier type. See the registry defined in {{iana-identifier}} 974 | for any others. 975 | 976 | value (required, string): 977 | : The identifier itself. 978 | 979 | notBefore (optional, string): 980 | : The requested value of the notBefore field in the certificate, in the date 981 | format defined in {{!RFC3339}}. 982 | 983 | notAfter (optional, string): 984 | : The requested value of the notAfter field in the certificate, in the date 985 | format defined in {{!RFC3339}}. 986 | 987 | error (optional, object): 988 | : The error that occurred while processing the order, if any. 989 | This field is structured as a problem document {{!RFC7807}}. 990 | 991 | authorizations (required, array of string): 992 | : For pending orders, the authorizations that the client needs to complete 993 | before the requested certificate can be issued (see 994 | {{identifier-authorization}}), including unexpired authorizations that the client has completed in the past for identifiers specified in the order. The authorizations required are dictated by server policy; there may not be a 1:1 relationship between the order identifiers and the authorizations required. For final orders (in the "valid" or "invalid" state), the authorizations that 995 | were completed. Each entry is a URL from which an authorization can be fetched 996 | with a POST-as-GET request. 997 | 998 | finalize (required, string): 999 | : A URL that a CSR must be POSTed to once all of the order's authorizations are 1000 | satisfied to finalize the order. The result of a successful finalization will be 1001 | the population of the certificate URL for the order. 1002 | 1003 | certificate (optional, string): 1004 | : A URL for the certificate that has been issued in response to this order. 1005 | 1006 | ~~~~~~~~~~ 1007 | { 1008 | "status": "valid", 1009 | "expires": "2016-01-20T14:09:07.99Z", 1010 | 1011 | "identifiers": [ 1012 | { "type": "dns", "value": "www.example.org" }, 1013 | { "type": "dns", "value": "example.org" } 1014 | ], 1015 | 1016 | "notBefore": "2016-01-01T00:00:00Z", 1017 | "notAfter": "2016-01-08T00:00:00Z", 1018 | 1019 | "authorizations": [ 1020 | "https://example.com/acme/authz/PAniVnsZcis", 1021 | "https://example.com/acme/authz/r4HqLzrSrpI" 1022 | ], 1023 | 1024 | "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", 1025 | 1026 | "certificate": "https://example.com/acme/cert/mAt3xBGaobw" 1027 | } 1028 | ~~~~~~~~~~ 1029 | 1030 | Any identifier of type "dns" in a newOrder request MAY have a wildcard domain 1031 | name as its value. A wildcard domain name consists of a single asterisk 1032 | character followed by a single full stop character ("\*.") followed by a domain 1033 | name as defined for use in the Subject Alternate Name Extension by 1034 | {{!RFC5280}}. An authorization returned by the server for a wildcard domain name 1035 | identifier MUST NOT include the asterisk and full stop ("\*.") prefix in the 1036 | authorization identifier value. The returned authorization MUST include the 1037 | optional "wildcard" field, with a value of true. 1038 | 1039 | The elements of the "authorizations" and "identifiers" arrays are immutable once 1040 | set. The server MUST NOT change the contents of either array after they are 1041 | created. If a client observes a change in the contents of either array, then it 1042 | SHOULD consider the order invalid. 1043 | 1044 | The "authorizations" array of the order SHOULD reflect all authorizations 1045 | that the CA takes into account in deciding to issue, even if some authorizations 1046 | were fulfilled in earlier orders or in pre-authorization transactions. For 1047 | example, if a CA allows multiple orders to be fulfilled based on a single 1048 | authorization transaction, then it SHOULD reflect that authorization in all of 1049 | the orders. 1050 | 1051 | Note that just because an authorization URL is listed in the 1052 | "authorizations" array of an order object doesn't mean that the 1053 | client is required to take action. There are several reasons that 1054 | the referenced authorizations may already be valid: 1055 | 1056 | * The client completed the authorization as part of a previous order 1057 | * The client previously pre-authorized the identifier (see {{pre-authorization}}) 1058 | * The server granted the client authorization based on an external account 1059 | 1060 | Clients SHOULD check the "status" field of an order to determine 1061 | whether they need to take any action. 1062 | 1063 | ### Authorization Objects 1064 | 1065 | An ACME authorization object represents a server's authorization for an account 1066 | to represent an identifier. In addition to the identifier, an authorization 1067 | includes several metadata fields, such as the status of the authorization (e.g., 1068 | "pending", "valid", or "revoked") and which challenges were used to validate 1069 | possession of the identifier. 1070 | 1071 | The structure of an ACME authorization resource is as follows: 1072 | 1073 | identifier (required, object): 1074 | : The identifier that the account is authorized to represent. 1075 | 1076 | type (required, string): 1077 | : The type of identifier (see below and {{iana-identifier}}). 1078 | 1079 | value (required, string): 1080 | : The identifier itself. 1081 | 1082 | status (required, string): 1083 | : The status of this authorization. Possible values are "pending", 1084 | "valid", "invalid", "deactivated", "expired", and "revoked". See 1085 | {{status-changes}}. 1086 | 1087 | expires (optional, string): 1088 | : The timestamp after which the server will consider this authorization invalid, 1089 | encoded in the format specified in {{!RFC3339}}. This field is REQUIRED 1090 | for objects with "valid" in the "status" field. 1091 | 1092 | challenges (required, array of objects): 1093 | : For pending authorizations, the challenges that the client can 1094 | fulfill in order to prove possession of the identifier. For valid 1095 | authorizations, the challenge that was validated. For invalid 1096 | authorizations, the challenge that was attempted and failed. Each 1097 | array entry is an object with parameters required to validate the 1098 | challenge. A client should attempt to fulfill one of these 1099 | challenges, and a server should consider any one of the challenges 1100 | sufficient to make the authorization valid. 1101 | 1102 | wildcard (optional, boolean): 1103 | : This field MUST be present and true for authorizations created as 1104 | a result of a newOrder request containing a DNS identifier with a 1105 | value that was a wildcard domain name. For other authorizations, 1106 | it MUST be absent. Wildcard domain names are described in {{order-objects}}. 1107 | 1108 | The only type of identifier defined by this specification is a fully qualified 1109 | domain name (type: "dns"). The domain name MUST be encoded in the 1110 | form in which it would appear in a certificate. That is, it MUST be 1111 | encoded according to the rules in Section 7 of {{!RFC5280}}. Servers MUST verify 1112 | any identifier values that begin with the ASCII-Compatible Encoding prefix 1113 | "xn\-\-" as defined in {{!RFC5890}} are properly encoded. Wildcard domain names 1114 | (with "\*" as the first label) MUST NOT be included in authorization objects. If 1115 | an authorization object conveys authorization for the base domain of a newOrder 1116 | DNS identifier containing a wildcard domain name, then the optional authorizations 1117 | "wildcard" field MUST be present with a value of true. 1118 | 1119 | {{identifier-validation-challenges}} describes a set of challenges for domain 1120 | name validation. 1121 | 1122 | ~~~~~~~~~~ 1123 | { 1124 | "status": "valid", 1125 | "expires": "2015-03-01T14:09:07.99Z", 1126 | 1127 | "identifier": { 1128 | "type": "dns", 1129 | "value": "www.example.org" 1130 | }, 1131 | 1132 | "challenges": [ 1133 | { 1134 | "url": "https://example.com/acme/chall/prV_B7yEyA4", 1135 | "type": "http-01", 1136 | "status": "valid", 1137 | "token": "DGyRejmCefe7v4NfDGDKfA", 1138 | "validated": "2014-12-01T12:05:58.16Z" 1139 | } 1140 | ], 1141 | 1142 | "wildcard": false 1143 | } 1144 | ~~~~~~~~~~ 1145 | 1146 | ### Challenge Objects 1147 | 1148 | An ACME challenge object represents a server's offer to validate a 1149 | client's possession of an identifier in a specific way. Unlike the 1150 | other objects listed above, there is not a single standard structure 1151 | for a challenge object. The contents of a challenge object depend 1152 | on the validation method being used. The general structure of 1153 | challenge objects and an initial set of validation methods are 1154 | described in {{identifier-validation-challenges}}. 1155 | 1156 | ### Status Changes 1157 | 1158 | Each ACME object type goes through a simple state machine over its 1159 | lifetime. The "status" field of the object indicates which state 1160 | the object is currently in. 1161 | 1162 | Challenge objects are created in the "pending" state. They 1163 | transition to the "processing" state when the client responds to the 1164 | challenge (see {{responding-to-challenges}}) and the server begins 1165 | attempting to validate that the client has completed the challenge. 1166 | Note that within the "processing" state, the server may attempt to 1167 | validate the challenge multiple times (see {{retrying-challenges}}). 1168 | Likewise, client requests for retries do not cause a state change. 1169 | If validation is successful, the challenge moves to the "valid" 1170 | state; if there is an error, the challenge moves to the "invalid" 1171 | state. 1172 | 1173 | ~~~~~~~~~~ 1174 | pending 1175 | | 1176 | | Receive 1177 | | response 1178 | V 1179 | processing <-+ 1180 | | | | Server retry or 1181 | | | | client retry request 1182 | | +----+ 1183 | | 1184 | | 1185 | Successful | Failed 1186 | validation | validation 1187 | +---------+---------+ 1188 | | | 1189 | V V 1190 | valid invalid 1191 | ~~~~~~~~~~ 1192 | {: title="State Transitions for Challenge Objects"} 1193 | 1194 | Authorization objects are created in the "pending" state. If one of 1195 | the challenges listed in the authorization transitions to the 1196 | "valid" state, then the authorization also changes to the "valid" 1197 | state. If the client attempts to fulfill a challenge and fails, or 1198 | if there is an error while the authorization is still 1199 | pending, then the authorization transitions to the "invalid" state. 1200 | Once the authorization is in the "valid" state, it can expire 1201 | ("expired"), be deactivated by the client ("deactivated", see 1202 | {{deactivating-an-authorization}}), or revoked by the server 1203 | ("revoked"). 1204 | 1205 | ~~~~~~~~~~ 1206 | pending --------------------+ 1207 | | | 1208 | Challenge failure | | 1209 | or | | 1210 | Error | Challenge valid | 1211 | +---------+---------+ | 1212 | | | | 1213 | V V | 1214 | invalid valid | 1215 | | | 1216 | | | 1217 | | | 1218 | +--------------+--------------+ 1219 | | | | 1220 | | | | 1221 | Server | Client | Time after | 1222 | revoke | deactivate | "expires" | 1223 | V V V 1224 | revoked deactivated expired 1225 | ~~~~~~~~~~ 1226 | {: title="State Transitions for Authorization Objects"} 1227 | 1228 | Order objects are created in the "pending" state. Once all of the 1229 | authorizations listed in the order object are in the "valid" state, 1230 | the order transitions to the "ready" state. The order moves to the 1231 | "processing" state after the client submits a request to the order's 1232 | "finalize" URL and the CA begins the issuance process for the 1233 | certificate. Once the certificate is issued, the order enters the 1234 | "valid" state. If an error occurs at any of these stages, the 1235 | order moves to the "invalid" state. The order also moves to the 1236 | "invalid" state if it expires or one of its authorizations enters a 1237 | final state other than "valid" ("expired", "revoked", or "deactivated"). 1238 | 1239 | ~~~~~~~~~~ 1240 | pending --------------+ 1241 | | | 1242 | | All authz | 1243 | | "valid" | 1244 | V | 1245 | ready ---------------+ 1246 | | | 1247 | | Receive | 1248 | | finalize | 1249 | | request | 1250 | V | 1251 | processing ------------+ 1252 | | | 1253 | | Certificate | Error or 1254 | | issued | Authorization failure 1255 | V V 1256 | valid invalid 1257 | ~~~~~~~~~~ 1258 | {: title="State Transitions for Order Objects"} 1259 | 1260 | Account objects are created in the "valid" state, since no further 1261 | action is required to create an account after a successful 1262 | newAccount request. If the account is deactivated by the client or 1263 | revoked by the server, it moves to the corresponding state. 1264 | 1265 | ~~~~~~~~~~ 1266 | valid 1267 | | 1268 | | 1269 | +-----------+-----------+ 1270 | Client | Server | 1271 | deactiv.| revoke | 1272 | V V 1273 | deactivated revoked 1274 | ~~~~~~~~~~ 1275 | {: title="State Transitions for Account Objects"} 1276 | 1277 | Note that some of these states may not ever appear in a "status" 1278 | field, depending on server behavior. For example, a server that 1279 | issues synchronously will never show an order in the "processing" 1280 | state. A server that deletes expired authorizations immediately 1281 | will never show an authorization in the "expired" state. 1282 | 1283 | 1284 | ## Getting a Nonce 1285 | 1286 | Before sending a POST request to the server, an ACME client needs to have a 1287 | fresh anti-replay nonce to put in the "nonce" header of the JWS. In most cases, 1288 | the client will have gotten a nonce from a previous request. However, the 1289 | client might sometimes need to get a new nonce, e.g., on its first request to 1290 | the server or if an existing nonce is no longer valid. 1291 | 1292 | To get a fresh nonce, the client sends a HEAD request to the newNonce resource 1293 | on the server. The server's response MUST include a Replay-Nonce header field 1294 | containing a fresh nonce and SHOULD have status code 200 (OK). The 1295 | server MUST also respond to GET requests for this resource, returning an empty 1296 | body (while still providing a Replay-Nonce header) with a status code of 204 (No Content). 1297 | 1298 | ~~~~~~~~~~ 1299 | HEAD /acme/new-nonce HTTP/1.1 1300 | Host: example.com 1301 | 1302 | HTTP/1.1 200 OK 1303 | Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA 1304 | Cache-Control: no-store 1305 | Link: ;rel="index" 1306 | ~~~~~~~~~~ 1307 | 1308 | Proxy caching of responses from the newNonce resource can cause 1309 | clients to receive the same nonce repeatedly, leading to "badNonce" errors. 1310 | The server MUST include a Cache-Control header field with the "no-store" 1311 | directive in responses for the newNonce resource, in order to prevent 1312 | caching of this resource. 1313 | 1314 | ## Account Management 1315 | 1316 | In this section, we describe how an ACME client can create an 1317 | account on an ACME server and perform some modifications to the 1318 | account after it has been created. 1319 | 1320 | A client creates a new account with the server by sending a POST request to the 1321 | server's newAccount URL. The body of the request is a stub account object 1322 | containing some subset of the following fields: 1323 | 1324 | contact (optional, array of string): 1325 | : Same meaning as the corresponding server field defined in {{account-objects}}. 1326 | 1327 | termsOfServiceAgreed (optional, boolean): 1328 | : Same meaning as the corresponding server field defined in {{account-objects}}. 1329 | 1330 | onlyReturnExisting (optional, boolean): 1331 | : If this field is present with the value "true", then the server MUST NOT 1332 | create a new account if one does not already exist. This allows a client to 1333 | look up an account URL based on an account key (see 1334 | {{finding-an-account-url-given-a-key}}). 1335 | 1336 | externalAccountBinding (optional, object): 1337 | : Same meaning as the corresponding server field defined in {{account-objects}} 1338 | 1339 | ~~~~~~~~~~ 1340 | POST /acme/new-account HTTP/1.1 1341 | Host: example.com 1342 | Content-Type: application/jose+json 1343 | 1344 | { 1345 | "protected": base64url({ 1346 | "alg": "ES256", 1347 | "jwk": {...}, 1348 | "nonce": "6S8IqOGY7eL2lsGoTZYifg", 1349 | "url": "https://example.com/acme/new-account" 1350 | }), 1351 | "payload": base64url({ 1352 | "termsOfServiceAgreed": true, 1353 | "contact": [ 1354 | "mailto:cert-admin@example.org", 1355 | "mailto:admin@example.org" 1356 | ] 1357 | }), 1358 | "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I" 1359 | } 1360 | ~~~~~~~~~~ 1361 | 1362 | The server MUST ignore any values provided in the "orders" fields in account 1363 | objects sent by the client, as well as any other fields that it does not 1364 | recognize. If new fields are specified in the future, the specification of those 1365 | fields MUST describe whether they can be provided by the client. The server MUST 1366 | NOT reflect the "onlyReturnExisting" field or any unrecognized fields in the 1367 | resulting account object. This allows clients to detect when servers do not 1368 | support an extension field. 1369 | 1370 | The server SHOULD validate that the contact URLs in the "contact" field are 1371 | valid and supported by the server. If the server validates contact URLs, it MUST 1372 | support the "mailto" scheme. Clients MUST NOT provide a "mailto" URL in the 1373 | "contact" field that contains `hfields` {{!RFC6068}} or more than one 1374 | `addr-spec` in the `to` component. If a server encounters a "mailto" contact 1375 | URL that does not meet these criteria, then it SHOULD reject it as invalid. 1376 | 1377 | If the server rejects a contact URL for using an 1378 | unsupported scheme, it MUST return an error of type "unsupportedContact", with 1379 | a description of the error and what types of contact URLs the server 1380 | considers acceptable. If the server rejects a contact URL for using a supported 1381 | scheme but an invalid value, then the server MUST return an error of type 1382 | "invalidContact". 1383 | 1384 | If the server wishes to require the client to agree to terms under which the ACME 1385 | service is to be used, it MUST indicate the URL where such terms can be accessed 1386 | in the "termsOfService" subfield of the "meta" field in the directory object, 1387 | and the server MUST reject newAccount requests that do not have the 1388 | "termsOfServiceAgreed" field set to "true". Clients SHOULD NOT automatically agree 1389 | to terms by default. Rather, they SHOULD require some user interaction for 1390 | agreement to terms. 1391 | 1392 | The server creates an account and stores the public key used to verify the 1393 | JWS (i.e., the "jwk" element of the JWS header) to authenticate future requests 1394 | from the account. The server returns this account object in a 201 (Created) 1395 | response, with the account URL in a Location header field. The account URL is 1396 | used as the "kid" value in the JWS authenticating subsequent requests by this 1397 | account (see {{request-authentication}}). The account URL is also used for 1398 | requests for management actions on this account, as described below. 1399 | 1400 | ~~~~~~~~~~ 1401 | HTTP/1.1 201 Created 1402 | Content-Type: application/json 1403 | Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA 1404 | Link: ;rel="index" 1405 | Location: https://example.com/acme/acct/evOfKhNU60wg 1406 | 1407 | { 1408 | "status": "valid", 1409 | 1410 | "contact": [ 1411 | "mailto:cert-admin@example.org", 1412 | "mailto:admin@example.org" 1413 | ], 1414 | 1415 | "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders" 1416 | } 1417 | ~~~~~~~~~~ 1418 | 1419 | ### Finding an Account URL Given a Key 1420 | 1421 | If the server receives a newAccount request signed with a key for which it already has an account registered with the provided account key, 1422 | then it MUST return a response with status code 200 (OK) and provide the URL of 1423 | that account in the Location header field. The body of this response represents the account object as it existed on the server before this request; any fields in the request object MUST be ignored. This allows a client that has 1424 | an account key but not the corresponding account URL to recover the account URL. 1425 | 1426 | If a client wishes to find the URL for an existing account and does not want an 1427 | account to be created if one does not already exist, then it SHOULD do so by 1428 | sending a POST request to the newAccount URL with a JWS whose payload has an 1429 | "onlyReturnExisting" field set to "true" ({"onlyReturnExisting": true}). 1430 | If a client sends such a request and an account does not exist, then the server 1431 | MUST return an error response with status code 400 (Bad Request) and type 1432 | "urn:ietf:params:acme:error:accountDoesNotExist". 1433 | 1434 | ### Account Update 1435 | 1436 | If the client wishes to update this information in the future, it sends a POST 1437 | request with updated information to the account URL. The server MUST ignore any 1438 | updates to the "orders" field, "termsOfServiceAgreed" field (see {{changes-of-terms-of-service}}), the "status" field (except as allowed by {{account-deactivation}}), or any other fields it does not recognize. If the server 1439 | accepts the update, it MUST return a response with a 200 (OK) status code and the 1440 | resulting account object. 1441 | 1442 | For example, to update the contact information in the above account, the client 1443 | could send the following request: 1444 | 1445 | ~~~~~~~~~~ 1446 | POST /acme/acct/evOfKhNU60wg HTTP/1.1 1447 | Host: example.com 1448 | Content-Type: application/jose+json 1449 | 1450 | { 1451 | "protected": base64url({ 1452 | "alg": "ES256", 1453 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1454 | "nonce": "ax5RnthDqp_Yf4_HZnFLmA", 1455 | "url": "https://example.com/acme/acct/evOfKhNU60wg" 1456 | }), 1457 | "payload": base64url({ 1458 | "contact": [ 1459 | "mailto:certificates@example.org", 1460 | "mailto:admin@example.org" 1461 | ] 1462 | }), 1463 | "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" 1464 | } 1465 | ~~~~~~~~~~ 1466 | 1467 | ### Changes of Terms of Service 1468 | 1469 | As described above, a client can indicate its agreement with the CA's terms of 1470 | service by setting the "termsOfServiceAgreed" field in its account object to 1471 | "true". 1472 | 1473 | If the server has changed its terms of service since a client initially agreed, 1474 | and the server is unwilling to process a request without explicit agreement to 1475 | the new terms, then it MUST return an error response with status code 403 1476 | (Forbidden) and type "urn:ietf:params:acme:error:userActionRequired". This 1477 | response MUST include a Link header field with link relation "terms-of-service" and 1478 | the latest terms-of-service URL. 1479 | 1480 | The problem document returned with the error MUST also include an "instance" 1481 | field, indicating a URL that the client should direct a human user to visit in 1482 | order for instructions on how to agree to the terms. 1483 | 1484 | ~~~~~ 1485 | HTTP/1.1 403 Forbidden 1486 | Replay-Nonce: T81bdZroZ2ITWSondpTmAw 1487 | Link: ;rel="index" 1488 | Link: ;rel="terms-of-service" 1489 | Content-Type: application/problem+json 1490 | Content-Language: en 1491 | 1492 | { 1493 | "type": "urn:ietf:params:acme:error:userActionRequired", 1494 | "detail": "Terms of service have changed", 1495 | "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8" 1496 | } 1497 | ~~~~~ 1498 | 1499 | ### External Account Binding 1500 | 1501 | The server MAY require a value for the "externalAccountBinding" field to be 1502 | present in "newAccount" requests. This can be used to associate an ACME account with an 1503 | existing account in a non-ACME system, such as a CA customer database. 1504 | 1505 | To enable ACME account binding, the CA operating the ACME server needs to provide the ACME client with a 1506 | MAC key and a key identifier, using some mechanism outside of ACME. The key 1507 | identifier MUST be an ASCII string. The MAC key SHOULD be provided in 1508 | base64url-encoded form, to maximize compatibility between non-ACME provisioning systems 1509 | and ACME clients. 1510 | 1511 | The ACME client then computes a binding JWS to indicate the external account holder's 1512 | approval of the ACME account key. The payload of this JWS is the ACME account key 1513 | being registered, in JWK form. The protected header of the JWS MUST meet the 1514 | following criteria: 1515 | 1516 | * The "alg" field MUST indicate a MAC-based algorithm 1517 | * The "kid" field MUST contain the key identifier provided by the CA 1518 | * The "nonce" field MUST NOT be present 1519 | * The "url" field MUST be set to the same value as the outer JWS 1520 | 1521 | The "signature" field of the JWS will contain the MAC value computed with the 1522 | MAC key provided by the CA. 1523 | 1524 | ~~~~~ 1525 | POST /acme/new-account HTTP/1.1 1526 | Host: example.com 1527 | Content-Type: application/jose+json 1528 | 1529 | { 1530 | "protected": base64url({ 1531 | "alg": "ES256", 1532 | "jwk": /* account key */, 1533 | "nonce": "K60BWPrMQG9SDxBDS_xtSw", 1534 | "url": "https://example.com/acme/new-account" 1535 | }), 1536 | "payload": base64url({ 1537 | "contact": [ 1538 | "mailto:cert-admin@example.org", 1539 | "mailto:admin@example.org" 1540 | ], 1541 | "termsOfServiceAgreed": true, 1542 | 1543 | "externalAccountBinding": { 1544 | "protected": base64url({ 1545 | "alg": "HS256", 1546 | "kid": /* key identifier from CA */, 1547 | "url": "https://example.com/acme/new-account" 1548 | }), 1549 | "payload": base64url(/* same as in "jwk" above */), 1550 | "signature": /* MAC using MAC key from CA */ 1551 | } 1552 | }), 1553 | "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1554 | } 1555 | ~~~~~ 1556 | 1557 | If such a CA requires that newAccount requests contain an "externalAccountBinding" 1558 | field, then it MUST provide the value "true" in the "externalAccountRequired" subfield 1559 | of the "meta" field in the directory object. If the CA receives a 1560 | newAccount request without an "externalAccountBinding" field, then it SHOULD 1561 | reply with an error of type "externalAccountRequired". 1562 | 1563 | When a CA receives a newAccount request containing an 1564 | "externalAccountBinding" field, it decides whether or not to verify the 1565 | binding. If the CA does not verify the binding, then it MUST NOT reflect the 1566 | "externalAccountBinding" field in the resulting account object (if any). To 1567 | verify the account binding, the CA MUST take the following steps: 1568 | 1569 | 1. Verify that the value of the field is a well-formed JWS 1570 | 2. Verify that the JWS protected field meets the above criteria 1571 | 3. Retrieve the MAC key corresponding to the key identifier in the "kid" field 1572 | 4. Verify that the MAC on the JWS verifies using that MAC key 1573 | 5. Verify that the payload of the JWS represents the same key as was used to 1574 | verify the outer JWS (i.e., the "jwk" field of the outer JWS) 1575 | 1576 | If all of these checks pass and the CA creates a new account, then the CA may 1577 | consider the new account associated with the external account corresponding to 1578 | the MAC key. The account object the CA returns MUST include an 1579 | "externalAccountBinding" field with the same value as the field in 1580 | the request. If any of these checks fail, then the CA MUST 1581 | reject the newAccount request. 1582 | 1583 | 1584 | ### Account Key Rollover {#account-key-roll-over} 1585 | 1586 | A client may wish to change the public key that is associated with an account in 1587 | order to recover from a key compromise or proactively mitigate the impact of an 1588 | unnoticed key compromise. 1589 | 1590 | To change the key associated with an account, the client sends a 1591 | request to the server containing signatures by both the old and new 1592 | keys. The signature by the new key covers the account URL and the 1593 | old key, signifying a request by the new key holder to take over the 1594 | account from the old key holder. The signature by the old key 1595 | covers this request and its signature, and indicates the old key 1596 | holder's assent to the rollover request. 1597 | 1598 | To create this request object, the client first constructs a 1599 | keyChange object describing the account to be updated and its 1600 | account key: 1601 | 1602 | account (required, string): 1603 | : The URL for the account being modified. The content of this field MUST be the 1604 | exact string provided in the Location header field in response to the 1605 | newAccount request that created the account. 1606 | 1607 | oldKey (required, JWK): 1608 | : The JWK representation of the old key. 1609 | 1610 | The client then encapsulates the keyChange object in an "inner" JWS, signed with the 1611 | requested new account key. 1612 | This "inner" JWS becomes the payload for the "outer" JWS that is the body of the ACME 1613 | request. 1614 | 1615 | The outer JWS MUST meet the normal requirements for an ACME JWS request body (see 1616 | {{request-authentication}}). The inner JWS MUST meet the normal requirements, 1617 | with the following differences: 1618 | 1619 | * The inner JWS MUST have a "jwk" header parameter, containing the public key of 1620 | the new key pair. 1621 | * The inner JWS MUST have the same "url" header parameter as the outer JWS. 1622 | * The inner JWS MUST omit the "nonce" header parameter. 1623 | 1624 | This transaction has signatures from both the old and new keys so that the 1625 | server can verify that the holders of the two keys both agree to the change. 1626 | The signatures are nested to preserve the property that all signatures on POST 1627 | messages are signed by exactly one key. The "inner" JWS effectively 1628 | represents a request by the holder of the new key to take over the 1629 | account form the holder of the old key. The "outer" JWS represents 1630 | the current account holder's assent to this request. 1631 | 1632 | ~~~~~~~~~~ 1633 | POST /acme/key-change HTTP/1.1 1634 | Host: example.com 1635 | Content-Type: application/jose+json 1636 | 1637 | { 1638 | "protected": base64url({ 1639 | "alg": "ES256", 1640 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1641 | "nonce": "S9XaOcxP5McpnTcWPIhYuB", 1642 | "url": "https://example.com/acme/key-change" 1643 | }), 1644 | "payload": base64url({ 1645 | "protected": base64url({ 1646 | "alg": "ES256", 1647 | "jwk": /* new key */, 1648 | "url": "https://example.com/acme/key-change" 1649 | }), 1650 | "payload": base64url({ 1651 | "account": "https://example.com/acme/acct/evOfKhNU60wg", 1652 | "oldKey": /* old key */ 1653 | }), 1654 | "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU" 1655 | }), 1656 | "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" 1657 | } 1658 | ~~~~~~~~~~ 1659 | 1660 | On receiving a keyChange request, the server MUST perform the following steps in 1661 | addition to the typical JWS validation: 1662 | 1663 | 1. Validate the POST request belongs to a currently active account, as described 1664 | in {{message-transport}}. 1665 | 2. Check that the payload of the JWS is a well-formed JWS object (the "inner 1666 | JWS"). 1667 | 3. Check that the JWS protected header of the inner JWS has a "jwk" field. 1668 | 4. Check that the inner JWS verifies using the key in its "jwk" field. 1669 | 5. Check that the payload of the inner JWS is a well-formed keyChange object 1670 | (as described above). 1671 | 6. Check that the "url" parameters of the inner and outer JWSs are the same. 1672 | 7. Check that the "account" field of the keyChange object contains the URL for 1673 | the account matching the old key (i.e., the "kid" field in the 1674 | outer JWS). 1675 | 8. Check that the "oldKey" field of the keyChange object is the 1676 | same as the account key for the account in question. 1677 | 9. Check that no account exists whose account key is the same as the key in the 1678 | "jwk" header parameter of the inner JWS. 1679 | 1680 | If all of these checks pass, then the server updates the corresponding account 1681 | by replacing the old account key with the new public key and returns status 1682 | code 200 (OK). Otherwise, the server responds with an error status code and a 1683 | problem document describing the error. If there is an existing account with 1684 | the new key provided, then the server SHOULD use status code 409 (Conflict) and 1685 | provide the URL of that account in the Location header field. 1686 | 1687 | Note that changing the account key for an account SHOULD NOT have any other 1688 | impact on the account. For example, the server MUST NOT invalidate pending 1689 | orders or authorization transactions based on a change of account key. 1690 | 1691 | ### Account Deactivation 1692 | 1693 | A client can deactivate an account by posting a signed update to the account URL with 1694 | a status field of "deactivated". Clients may wish to do this when the account 1695 | key is compromised or decommissioned. A deactivated account can no longer request 1696 | certificate issuance or access resources related to the account, such as orders 1697 | or authorizations. If a server receives a POST or POST-as-GET from 1698 | a deactivated account, it MUST return an error response with status 1699 | code 401 (Unauthorized) and type "urn:ietf:params:acme:error:unauthorized". 1700 | 1701 | ~~~~~~~~~~ 1702 | POST /acme/acct/evOfKhNU60wg HTTP/1.1 1703 | Host: example.com 1704 | Content-Type: application/jose+json 1705 | 1706 | { 1707 | "protected": base64url({ 1708 | "alg": "ES256", 1709 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1710 | "nonce": "ntuJWWSic4WVNSqeUmshgg", 1711 | "url": "https://example.com/acme/acct/evOfKhNU60wg" 1712 | }), 1713 | "payload": base64url({ 1714 | "status": "deactivated" 1715 | }), 1716 | "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y" 1717 | } 1718 | ~~~~~~~~~~ 1719 | 1720 | The server MUST verify that the request is signed by the account key. If the 1721 | server accepts the deactivation request, it replies with a 200 (OK) status code 1722 | and the current contents of the account object. 1723 | 1724 | Once an account is deactivated, the server MUST NOT accept further requests 1725 | authorized by that account's key. The server SHOULD cancel any pending operations authorized 1726 | by the account's key, such as certificate orders. A server may take a variety of actions in 1727 | response to an account deactivation, e.g., deleting data related to that account 1728 | or sending mail to the account's contacts. Servers SHOULD NOT revoke 1729 | certificates issued by the deactivated account, since this could cause 1730 | operational disruption for servers using these certificates. ACME does not 1731 | provide a way to reactivate a deactivated account. 1732 | 1733 | ## Applying for Certificate Issuance 1734 | 1735 | The client begins the certificate issuance process by sending a POST request to the server's 1736 | newOrder resource. The body of the POST is a JWS object whose JSON payload is 1737 | a subset of the order object defined in {{order-objects}}, containing the fields 1738 | that describe the certificate to be issued: 1739 | 1740 | identifiers (required, array of object): 1741 | : An array of identifier objects that the client wishes to submit an order for. 1742 | 1743 | type (required, string): 1744 | : The type of identifier. 1745 | 1746 | value (required, string): 1747 | : The identifier itself. 1748 | 1749 | notBefore (optional, string): 1750 | : The requested value of the notBefore field in the certificate, in the date 1751 | format defined in {{!RFC3339}}. 1752 | 1753 | notAfter (optional, string): 1754 | : The requested value of the notAfter field in the certificate, in the date 1755 | format defined in {{!RFC3339}}. 1756 | 1757 | ~~~~~~~~~~ 1758 | POST /acme/new-order HTTP/1.1 1759 | Host: example.com 1760 | Content-Type: application/jose+json 1761 | 1762 | { 1763 | "protected": base64url({ 1764 | "alg": "ES256", 1765 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1766 | "nonce": "5XJ1L3lEkMG7tR6pA00clA", 1767 | "url": "https://example.com/acme/new-order" 1768 | }), 1769 | "payload": base64url({ 1770 | "identifiers": [ 1771 | { "type": "dns", "value": "www.example.org" }, 1772 | { "type": "dns", "value": "example.org" } 1773 | ], 1774 | "notBefore": "2016-01-01T00:04:00+04:00", 1775 | "notAfter": "2016-01-08T00:04:00+04:00" 1776 | }), 1777 | "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 1778 | } 1779 | ~~~~~~~~~~ 1780 | 1781 | The server MUST return an error if it cannot fulfill the request as specified, 1782 | and it MUST NOT issue a certificate with contents other than those requested. If 1783 | the server requires the request to be modified in a certain way, it should 1784 | indicate the required changes using an appropriate error type and description. 1785 | 1786 | If the server is willing to issue the requested certificate, it responds with a 1787 | 201 (Created) response. The body of this response is an order object reflecting 1788 | the client's request and any authorizations the client must complete before the 1789 | certificate will be issued. 1790 | 1791 | ~~~~~~~~~~ 1792 | HTTP/1.1 201 Created 1793 | Replay-Nonce: MYAuvOpaoIiywTezizk5vw 1794 | Link: ;rel="index" 1795 | Location: https://example.com/acme/order/TOlocE8rfgo 1796 | 1797 | { 1798 | "status": "pending", 1799 | "expires": "2016-01-05T14:09:07.99Z", 1800 | 1801 | "notBefore": "2016-01-01T00:00:00Z", 1802 | "notAfter": "2016-01-08T00:00:00Z", 1803 | 1804 | "identifiers": [ 1805 | { "type": "dns", "value": "www.example.org" }, 1806 | { "type": "dns", "value": "example.org" } 1807 | ], 1808 | 1809 | "authorizations": [ 1810 | "https://example.com/acme/authz/PAniVnsZcis", 1811 | "https://example.com/acme/authz/r4HqLzrSrpI" 1812 | ], 1813 | 1814 | "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize" 1815 | } 1816 | ~~~~~~~~~~ 1817 | 1818 | The order object returned by the server represents a promise that if the 1819 | client fulfills the server's requirements before the "expires" time, then the 1820 | server will be willing to finalize the order upon request and issue the 1821 | requested certificate. In the order object, any authorization referenced in the 1822 | "authorizations" array whose status is "pending" represents an authorization 1823 | transaction that the client must complete before the server will issue the 1824 | certificate (see {{identifier-authorization}}). If the client fails to complete 1825 | the required actions before the "expires" time, then the server SHOULD change 1826 | the status of the order to "invalid" and MAY delete the order resource. Clients 1827 | MUST NOT make any assumptions about the sort order of "identifiers" or 1828 | "authorizations" elements in the returned order object. 1829 | 1830 | Once the client believes it has fulfilled the server's requirements, it should 1831 | send a POST request to the order resource's finalize URL. The POST body MUST 1832 | include a CSR: 1833 | 1834 | csr (required, string): 1835 | : A CSR encoding the parameters for the certificate being requested {{!RFC2986}}. 1836 | The CSR is sent in the base64url-encoded version of the DER format. (Note: 1837 | Because this field uses base64url, and does not include headers, it is different 1838 | from PEM.) 1839 | 1840 | ~~~~~~~~~~ 1841 | POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1 1842 | Host: example.com 1843 | Content-Type: application/jose+json 1844 | 1845 | { 1846 | "protected": base64url({ 1847 | "alg": "ES256", 1848 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1849 | "nonce": "MSF2j2nawWHPxxkE3ZJtKQ", 1850 | "url": "https://example.com/acme/order/TOlocE8rfgo/finalize" 1851 | }), 1852 | "payload": base64url({ 1853 | "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", 1854 | }), 1855 | "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" 1856 | } 1857 | ~~~~~~~~~~ 1858 | 1859 | The CSR encodes the client's requests with regard to the content of the 1860 | certificate to be issued. The CSR MUST indicate the exact same set of requested 1861 | identifiers as the initial newOrder request. Identifiers of type "dns" MUST appear either in the commonName portion 1862 | of the requested subject name or in an extensionRequest attribute {{!RFC2985}} 1863 | requesting a subjectAltName extension, or both. (These identifiers may appear 1864 | in any sort order.) Specifications that define 1865 | new identifier types must specify where in the certificate signing 1866 | request these 1867 | identifiers can appear. 1868 | 1869 | A request to finalize an order will result in an error if the CA is unwilling to issue a certificate corresponding to the submitted CSR. For example: 1870 | 1871 | * If the CSR and order identifiers differ 1872 | * If the account is not authorized for the identifiers indicated in the CSR 1873 | * If the CSR requests extensions that the CA is not willing to include 1874 | 1875 | In such cases, the problem document returned by the server SHOULD 1876 | use error code "badCSR" and describe specific reasons the CSR was 1877 | rejected in its "detail" field. After returning such an error, the 1878 | server SHOULD leave the order in the "ready" state, to allow the 1879 | client to submit a new finalize request with an amended CSR. 1880 | 1881 | A request to finalize an order will result in error if the order is not in the 1882 | "ready" state. In such cases, the server MUST return a 403 (Forbidden) error 1883 | with a problem document of type "orderNotReady". The client should then send a 1884 | POST-as-GET request to the order resource to obtain its current state. The 1885 | status of the order will indicate what action the client should take (see 1886 | below). 1887 | 1888 | If a request to finalize an order is successful, the server will return a 200 1889 | (OK) with an updated order object. The status of the order will indicate what 1890 | action the client should take: 1891 | 1892 | * "invalid": The certificate will not be issued. Consider this order process 1893 | abandoned. 1894 | 1895 | * "pending": The server does not believe that the client has fulfilled the 1896 | requirements. Check the "authorizations" array for entries that are still 1897 | pending. 1898 | 1899 | * "ready": The server agrees that the requirements have been 1900 | fulfilled, and is awaiting finalization. Submit a finalization 1901 | request. 1902 | 1903 | * "processing": The certificate is being issued. Send a POST-as-GET request after the 1904 | time given in the Retry-After header field of the response, if 1905 | any. 1906 | 1907 | * "valid": The server has issued the certificate and provisioned its URL to the 1908 | "certificate" field of the order. Download the certificate. 1909 | 1910 | ~~~~~~~~~~ 1911 | HTTP/1.1 200 OK 1912 | Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X 1913 | Link: ;rel="index" 1914 | Location: https://example.com/acme/order/TOlocE8rfgo 1915 | 1916 | { 1917 | "status": "valid", 1918 | "expires": "2016-01-20T14:09:07.99Z", 1919 | 1920 | "notBefore": "2016-01-01T00:00:00Z", 1921 | "notAfter": "2016-01-08T00:00:00Z", 1922 | 1923 | "identifiers": [ 1924 | { "type": "dns", "value": "www.example.org" }, 1925 | { "type": "dns", "value": "example.org" } 1926 | ], 1927 | 1928 | "authorizations": [ 1929 | "https://example.com/acme/authz/PAniVnsZcis", 1930 | "https://example.com/acme/authz/r4HqLzrSrpI" 1931 | ], 1932 | 1933 | "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", 1934 | 1935 | "certificate": "https://example.com/acme/cert/mAt3xBGaobw" 1936 | } 1937 | ~~~~~~~~~~ 1938 | 1939 | ### Pre-authorization 1940 | 1941 | The order process described above presumes that authorization objects are 1942 | created reactively, in response to a certificate order. Some servers 1943 | may also wish to enable clients to obtain authorization for an identifier 1944 | proactively, outside of the context of a specific issuance. For example, a 1945 | client hosting virtual servers for a collection of names might wish to obtain 1946 | authorization before any virtual servers are created and only create a certificate when 1947 | a virtual server starts up. 1948 | 1949 | In some cases, a CA running an ACME server might have a completely external, 1950 | non-ACME process for authorizing a client to issue certificates for an identifier. In these 1951 | cases, the CA should provision its ACME server with authorization objects 1952 | corresponding to these authorizations and reflect them as already valid in any 1953 | orders submitted by the client. 1954 | 1955 | If a CA wishes to allow pre-authorization within ACME, it can offer a "new 1956 | authorization" resource in its directory by adding the field "newAuthz" with a 1957 | URL for the newAuthz resource. 1958 | 1959 | To request authorization for an identifier, the client sends a POST request to 1960 | the newAuthz resource specifying the identifier for which authorization 1961 | is being requested. 1962 | 1963 | identifier (required, object): 1964 | : The identifier to appear in the resulting authorization object 1965 | (see {{authorization-objects}}). 1966 | 1967 | type (required, string): 1968 | : The type of identifier. 1969 | 1970 | value (required, string): 1971 | : The identifier itself. 1972 | 1973 | ~~~~~~~~~~ 1974 | POST /acme/new-authz HTTP/1.1 1975 | Host: example.com 1976 | Content-Type: application/jose+json 1977 | 1978 | { 1979 | "protected": base64url({ 1980 | "alg": "ES256", 1981 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 1982 | "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 1983 | "url": "https://example.com/acme/new-authz" 1984 | }), 1985 | "payload": base64url({ 1986 | "identifier": { 1987 | "type": "dns", 1988 | "value": "example.org" 1989 | } 1990 | }), 1991 | "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 1992 | } 1993 | ~~~~~~~~~~ 1994 | 1995 | Note that because the identifier in a pre-authorization request is 1996 | the exact identifier to be included in the authorization object, 1997 | pre-authorization cannot be used to authorize issuance of certificates 1998 | containing wildcard domain names. 1999 | 2000 | Before processing the authorization request, the server SHOULD determine whether 2001 | it is willing to issue certificates for the identifier. For example, the server 2002 | should check that the identifier is of a supported type. Servers might also 2003 | check names against a blacklist of known high-value identifiers. If the server 2004 | is unwilling to issue for the identifier, it SHOULD return an error 2005 | with status code 403 (Forbidden), with a problem document describing 2006 | the reason for the rejection. 2007 | 2008 | If the server is willing to proceed, it builds a pending authorization object 2009 | from the inputs submitted by the client: 2010 | 2011 | * "identifier" the identifier submitted by the client 2012 | * "status" MUST be "pending" unless the server has out-of-band information 2013 | about the client's authorization status 2014 | * "challenges" as selected by the server's policy for this identifier 2015 | 2016 | The server allocates a new URL for this authorization and returns a 201 2017 | (Created) response with the authorization URL in the Location header field and 2018 | the JSON authorization object in the body. The client then follows the process 2019 | described in {{identifier-authorization}} to complete the authorization process. 2020 | 2021 | 2022 | ### Downloading the Certificate 2023 | 2024 | To download the issued certificate, the client simply sends a POST-as-GET request to the 2025 | certificate URL. 2026 | 2027 | The default format of the certificate is application/pem-certificate-chain (see {{iana-considerations}}). 2028 | 2029 | The server MAY provide one or more link relation header fields {{RFC5988}} with 2030 | relation "alternate". Each such field SHOULD express an alternative certificate 2031 | chain starting with the same end-entity certificate. This can be used to express 2032 | paths to various trust anchors. Clients can fetch these alternates and use their 2033 | own heuristics to decide which is optimal. 2034 | 2035 | ~~~~~~~~~~ 2036 | POST /acme/cert/mAt3xBGaobw HTTP/1.1 2037 | Host: example.com 2038 | Content-Type: application/jose+json 2039 | Accept: application/pem-certificate-chain 2040 | 2041 | { 2042 | "protected": base64url({ 2043 | "alg": "ES256", 2044 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2045 | "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2046 | "url": "https://example.com/acme/cert/mAt3xBGaobw" 2047 | }), 2048 | "payload": "", 2049 | "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2050 | } 2051 | 2052 | HTTP/1.1 200 OK 2053 | Content-Type: application/pem-certificate-chain 2054 | Link: ;rel="index" 2055 | 2056 | -----BEGIN CERTIFICATE----- 2057 | [End-entity certificate contents] 2058 | -----END CERTIFICATE----- 2059 | -----BEGIN CERTIFICATE----- 2060 | [Issuer certificate contents] 2061 | -----END CERTIFICATE----- 2062 | -----BEGIN CERTIFICATE----- 2063 | [Other certificate contents] 2064 | -----END CERTIFICATE----- 2065 | ~~~~~~~~~~ 2066 | 2067 | A certificate resource represents a single, immutable certificate. If the client 2068 | wishes to obtain a renewed certificate, the client initiates a new order process 2069 | to request one. 2070 | 2071 | Because certificate resources are immutable once issuance is complete, the 2072 | server MAY enable the caching of the resource by adding Expires and 2073 | Cache-Control header fields specifying a point in time in the distant future. These 2074 | header fields have no relation to the certificate's period of validity. 2075 | 2076 | The ACME client MAY request other formats by including an Accept 2077 | header field {{RFC7231}} in its request. For example, the client could use the media type 2078 | `application/pkix-cert` {{!RFC2585}} or `application/pkcs7-mime` {{!RFC5751}} to request the end-entity certificate 2079 | in DER format. Server support for alternate formats is OPTIONAL. For 2080 | formats that can only express a single certificate, the server SHOULD 2081 | provide one or more `Link: rel="up"` header fields pointing to an issuer or 2082 | issuers so that ACME clients can build a certificate chain as defined 2083 | in TLS (see Section 4.4.2 of {{!RFC8446}}). 2084 | 2085 | ## Identifier Authorization 2086 | 2087 | The identifier authorization process establishes the authorization of an account 2088 | to manage certificates for a given identifier. This process assures the 2089 | server of two things: 2090 | 2091 | 1. That the client controls the private key of the account key pair, and 2092 | 2. That the client controls the identifier in question. 2093 | 2094 | This process may be repeated to associate multiple identifiers with an account 2095 | (e.g., to request certificates with multiple identifiers) or to associate 2096 | multiple accounts with an identifier (e.g., to allow multiple entities to manage 2097 | certificates). 2098 | 2099 | Authorization resources are created by the server in response to newOrder or 2100 | newAuthz requests submitted by an account key holder; their 2101 | URLs are provided to the client in the responses to these requests. The 2102 | authorization object is implicitly tied to the account key used to sign the 2103 | request. 2104 | 2105 | When a client receives an order from the server in reply to a newOrder request, it downloads the authorization 2106 | resources by sending POST-as-GET requests to the indicated URLs. If the client 2107 | initiates authorization using a request to the newAuthz resource, it 2108 | will have already received the pending authorization object in the response 2109 | to that request. 2110 | 2111 | ~~~~~~~~~~ 2112 | POST /acme/authz/PAniVnsZcis HTTP/1.1 2113 | Host: example.com 2114 | Content-Type: application/jose+json 2115 | 2116 | { 2117 | "protected": base64url({ 2118 | "alg": "ES256", 2119 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2120 | "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2121 | "url": "https://example.com/acme/authz/PAniVnsZcis" 2122 | }), 2123 | "payload": "", 2124 | "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2125 | } 2126 | 2127 | HTTP/1.1 200 OK 2128 | Content-Type: application/json 2129 | Link: ;rel="index" 2130 | 2131 | { 2132 | "status": "pending", 2133 | "expires": "2016-01-02T14:09:30Z", 2134 | 2135 | "identifier": { 2136 | "type": "dns", 2137 | "value": "www.example.org" 2138 | }, 2139 | 2140 | "challenges": [ 2141 | { 2142 | "type": "http-01", 2143 | "url": "https://example.com/acme/chall/prV_B7yEyA4", 2144 | "token": "DGyRejmCefe7v4NfDGDKfA" 2145 | }, 2146 | { 2147 | "type": "dns-01", 2148 | "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", 2149 | "token": "DGyRejmCefe7v4NfDGDKfA" 2150 | } 2151 | ] 2152 | } 2153 | ~~~~~~~~~~ 2154 | 2155 | ### Responding to Challenges 2156 | 2157 | To prove control of the identifier and receive authorization, the client needs to 2158 | provision the required challenge response based on the challenge type and 2159 | indicate to the server that it is ready for the challenge validation to 2160 | be attempted. 2161 | 2162 | The client indicates to the server that it is ready for the challenge validation by 2163 | sending an empty JSON body (`{}`) carried in a POST request to the challenge 2164 | URL (not the authorization URL). 2165 | 2166 | For example, if the client were to respond to the "http-01" challenge in the 2167 | above authorization, it would send the following request: 2168 | 2169 | ~~~~~~~~~~ 2170 | POST /acme/chall/prV_B7yEyA4 HTTP/1.1 2171 | Host: example.com 2172 | Content-Type: application/jose+json 2173 | 2174 | { 2175 | "protected": base64url({ 2176 | "alg": "ES256", 2177 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2178 | "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 2179 | "url": "https://example.com/acme/chall/prV_B7yEyA4" 2180 | }), 2181 | "payload": base64url({}), 2182 | "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 2183 | } 2184 | ~~~~~~~~~~ 2185 | 2186 | The server updates the authorization document by updating its representation of 2187 | the challenge with the response object provided by the client. The server MUST 2188 | ignore any fields in the response object that are not specified as response 2189 | fields for this type of challenge. 2190 | Note that the challenges in this document do 2191 | not define any response fields, but future specifications might define them. 2192 | The server provides a 200 (OK) response 2193 | with the updated challenge object as its body. 2194 | 2195 | If the client's response is invalid for any reason or does not provide the 2196 | server with appropriate information to validate the challenge, then the server 2197 | MUST return an HTTP error. On receiving such an error, the client SHOULD undo 2198 | any actions that have been taken to fulfill the challenge, e.g., removing files 2199 | that have been provisioned to a web server. 2200 | 2201 | The server is said to "finalize" the authorization when it has completed 2202 | one of the validations. This is done by assigning the authorization a status of "valid" 2203 | or "invalid", corresponding to whether it considers the account authorized 2204 | for the identifier. If the final state is "valid", then the server MUST include 2205 | an "expires" field. When finalizing an authorization, the server MAY remove 2206 | challenges other than the one that was completed, and it may modify the "expires" 2207 | field. The server SHOULD NOT remove challenges with status "invalid". 2208 | 2209 | Usually, the validation process will take some time, so the client will need to 2210 | poll the authorization resource to see when it is finalized. For challenges 2211 | where the client can tell when the server has validated the challenge (e.g., by 2212 | seeing an HTTP or DNS request from the server), the client SHOULD NOT begin 2213 | polling until it has seen the validation request from the server. 2214 | 2215 | To check on the status of an authorization, the client sends a POST-as-GET request to 2216 | the authorization URL, and the server responds with the current authorization 2217 | object. In responding to poll requests while the validation is still in 2218 | progress, the server MUST return a 200 (OK) response and MAY include a 2219 | Retry-After header field to suggest a polling interval to the client. 2220 | 2221 | ~~~~~~~~~~ 2222 | POST /acme/authz/PAniVnsZcis HTTP/1.1 2223 | Host: example.com 2224 | Content-Type: application/jose+json 2225 | 2226 | { 2227 | "protected": base64url({ 2228 | "alg": "ES256", 2229 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2230 | "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 2231 | "url": "https://example.com/acme/authz/PAniVnsZcis" 2232 | }), 2233 | "payload": "", 2234 | "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 2235 | } 2236 | 2237 | HTTP/1.1 200 OK 2238 | Content-Type: application/json 2239 | Link: ;rel="index" 2240 | 2241 | { 2242 | "status": "valid", 2243 | "expires": "2018-09-09T14:09:01.13Z", 2244 | 2245 | "identifier": { 2246 | "type": "dns", 2247 | "value": "www.example.org" 2248 | }, 2249 | 2250 | "challenges": [ 2251 | { 2252 | "type": "http-01", 2253 | "url": "https://example.com/acme/chall/prV_B7yEyA4", 2254 | "status": "valid", 2255 | "validated": "2014-12-01T12:05:13.72Z", 2256 | "token": "IlirfxKKXAsHtmzK29Pj8A" 2257 | } 2258 | ] 2259 | } 2260 | ~~~~~~~~~~ 2261 | 2262 | ### Deactivating an Authorization 2263 | 2264 | If a client wishes to relinquish its authorization to issue certificates for an 2265 | identifier, then it may request that the server deactivate each authorization 2266 | associated with it by sending POST requests with the static object 2267 | {"status": "deactivated"} to each authorization URL. 2268 | 2269 | ~~~~~~~~~~ 2270 | POST /acme/authz/PAniVnsZcis HTTP/1.1 2271 | Host: example.com 2272 | Content-Type: application/jose+json 2273 | 2274 | { 2275 | "protected": base64url({ 2276 | "alg": "ES256", 2277 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2278 | "nonce": "xWCM9lGbIyCgue8di6ueWQ", 2279 | "url": "https://example.com/acme/authz/PAniVnsZcis" 2280 | }), 2281 | "payload": base64url({ 2282 | "status": "deactivated" 2283 | }), 2284 | "signature": "srX9Ji7Le9bjszhu...WTFdtujObzMtZcx4" 2285 | } 2286 | ~~~~~~~~~~ 2287 | 2288 | The server MUST verify that the request is signed by the account key 2289 | corresponding to the account that owns the authorization. If the server accepts 2290 | the deactivation, it should reply with a 200 (OK) status code and the updated 2291 | contents of the authorization object. 2292 | 2293 | The server MUST NOT treat deactivated authorization objects as sufficient for 2294 | issuing certificates. 2295 | 2296 | ## Certificate Revocation 2297 | 2298 | To request that a certificate be revoked, the client sends a POST request to 2299 | the ACME server's revokeCert URL. The body of the POST is a JWS object whose 2300 | JSON payload contains the certificate to be revoked: 2301 | 2302 | certificate (required, string): 2303 | : The certificate to be revoked, in the base64url-encoded version of the DER 2304 | format. (Note: Because this field uses base64url, and does not include headers, 2305 | it is different from PEM.) 2306 | 2307 | reason (optional, int): 2308 | : One of the revocation reasonCodes defined in Section 5.3.1 of {{RFC5280}} 2309 | to be used when generating OCSP responses and CRLs. If this field is not set, 2310 | the server SHOULD omit the reasonCode CRL entry extension when generating OCSP 2311 | responses and CRLs. The server MAY disallow a subset of reasonCodes from being 2312 | used by the user. If a request contains a disallowed reasonCode, then the server MUST 2313 | reject it with the error type "urn:ietf:params:acme:error:badRevocationReason". 2314 | The problem document detail SHOULD indicate which reasonCodes are allowed. 2315 | 2316 | Revocation requests are different from other ACME requests in that they can be 2317 | signed with either an account key pair or the key pair in the certificate. 2318 | 2319 | Example using an account key pair for the signature: 2320 | 2321 | ~~~~~~~~~~ 2322 | POST /acme/revoke-cert HTTP/1.1 2323 | Host: example.com 2324 | Content-Type: application/jose+json 2325 | 2326 | { 2327 | "protected": base64url({ 2328 | "alg": "ES256", 2329 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2330 | "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2331 | "url": "https://example.com/acme/revoke-cert" 2332 | }), 2333 | "payload": base64url({ 2334 | "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2335 | "reason": 4 2336 | }), 2337 | "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2338 | } 2339 | ~~~~~~~~~~ 2340 | 2341 | Example using the certificate key pair for the signature: 2342 | 2343 | ~~~~~~~~~~ 2344 | POST /acme/revoke-cert HTTP/1.1 2345 | Host: example.com 2346 | Content-Type: application/jose+json 2347 | 2348 | { 2349 | "protected": base64url({ 2350 | "alg": "RS256", 2351 | "jwk": /* certificate's public key */, 2352 | "nonce": "JHb54aT_KTXBWQOzGYkt9A", 2353 | "url": "https://example.com/acme/revoke-cert" 2354 | }), 2355 | "payload": base64url({ 2356 | "certificate": "MIIEDTCCAvegAwIBAgIRAP8...", 2357 | "reason": 1 2358 | }), 2359 | "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2360 | } 2361 | ~~~~~~~~~~ 2362 | 2363 | Before revoking a certificate, the server MUST verify that the key used to sign 2364 | the request is authorized to revoke the certificate. The server MUST consider 2365 | at least the following accounts authorized for a given certificate: 2366 | 2367 | * the account that issued the certificate. 2368 | * an account that holds authorizations for all of the identifiers in the 2369 | certificate. 2370 | 2371 | The server MUST also consider a revocation request valid if it is signed with 2372 | the private key corresponding to the public key in the certificate. 2373 | 2374 | If the revocation succeeds, the server responds with status code 200 (OK). If 2375 | the revocation fails, the server returns an error. For example, if the certificate 2376 | has already been revoked, the server returns an error response with status code 400 2377 | (Bad Request) and type "urn:ietf:params:acme:error:alreadyRevoked". 2378 | 2379 | ~~~~~~~~~~ 2380 | HTTP/1.1 200 OK 2381 | Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw 2382 | Content-Length: 0 2383 | Link: ;rel="index" 2384 | 2385 | --- or --- 2386 | 2387 | HTTP/1.1 403 Forbidden 2388 | Replay-Nonce: lXfyFzi6238tfPQRwgfmPU 2389 | Content-Type: application/problem+json 2390 | Content-Language: en 2391 | Link: ;rel="index" 2392 | 2393 | { 2394 | "type": "urn:ietf:params:acme:error:unauthorized", 2395 | "detail": "No authorization provided for name example.org" 2396 | } 2397 | ~~~~~~~~~~ 2398 | 2399 | 2400 | # Identifier Validation Challenges 2401 | 2402 | There are few types of identifiers in the world for which there is a standardized 2403 | mechanism to prove possession of a given identifier. In all practical cases, 2404 | CAs rely on a variety of means to test whether an entity applying for a 2405 | certificate with a given identifier actually controls that identifier. 2406 | 2407 | Challenges provide the server with assurance that an account holder is also 2408 | the entity that controls an identifier. For each type of challenge, it must be 2409 | the case that, in order for an entity to successfully complete the challenge, the 2410 | entity must both: 2411 | 2412 | * Hold the private key of the account key pair used to respond to the challenge, and 2413 | * Control the identifier in question. 2414 | 2415 | {{security-considerations}} documents how the challenges defined in this 2416 | document meet these requirements. New challenges will need to document how they 2417 | do. 2418 | 2419 | ACME uses an extensible challenge/response framework for identifier validation. 2420 | The server presents a set of challenges in the authorization object it sends to a 2421 | client (as objects in the "challenges" array), and the client responds by 2422 | sending a response object in a POST request to a challenge URL. 2423 | 2424 | This section describes an initial set of challenge types. The definition of a 2425 | challenge type includes: 2426 | 2427 | 1. Content of challenge objects 2428 | 2. Content of response objects 2429 | 3. How the server uses the challenge and response to verify control of an 2430 | identifier 2431 | 2432 | Challenge objects all contain the following basic fields: 2433 | 2434 | type (required, string): 2435 | : The type of challenge encoded in the object. 2436 | 2437 | url (required, string): 2438 | : The URL to which a response can be posted. 2439 | 2440 | status (required, string): 2441 | : The status of this challenge. Possible values are "pending", 2442 | "processing", "valid", and "invalid" (see {{status-changes}}). 2443 | 2444 | validated (optional, string): 2445 | : The time at which the server validated this challenge, encoded in the 2446 | format specified in {{RFC3339}}. This field is REQUIRED if the 2447 | "status" field is "valid". 2448 | 2449 | error (optional, object): 2450 | : Error that occurred while the server was validating the challenge, if any, 2451 | structured as a problem document {{!RFC7807}}. Multiple errors can be indicated 2452 | by using subproblems {{subproblems}}. A challenge object with an error MUST have 2453 | status equal to "invalid". 2454 | 2455 | All additional fields are specified by the challenge type. If the server sets a 2456 | challenge's "status" to "invalid", it SHOULD also include the "error" field to 2457 | help the client diagnose why the challenge failed. 2458 | 2459 | Different challenges allow the server to obtain proof of different aspects of 2460 | control over an identifier. In some challenges, like HTTP and DNS, the 2461 | client directly proves its ability to do certain things related to the 2462 | identifier. The choice of which challenges to offer to a client under which 2463 | circumstances is a matter of server policy. 2464 | 2465 | The identifier validation challenges described in this section all relate to 2466 | validation of domain names. If ACME is extended in the future to support other 2467 | types of identifiers, there will need to be new challenge types, and they will 2468 | need to specify which types of identifier they apply to. 2469 | 2470 | ## Key Authorizations 2471 | 2472 | All challenges defined in this document make use of a key authorization 2473 | string. A key authorization is a string that concatenates the token for the 2474 | challenge with a key fingerprint, separated by a "." character: 2475 | 2476 | ~~~~~~~~~~ 2477 | keyAuthorization = token || '.' || base64url(Thumbprint(accountKey)) 2478 | ~~~~~~~~~~ 2479 | 2480 | The "Thumbprint" step indicates the computation specified in {{!RFC7638}}, 2481 | using the SHA-256 digest [FIPS180-4]. As noted in {{!RFC7518}} any prepended 2482 | zero octets in the fields of a JWK object MUST be stripped before doing the computation. 2483 | 2484 | As specified in the individual challenges below, the token for a challenge is a 2485 | string comprised entirely of characters in the URL-safe base64 alphabet. 2486 | The "||" operator indicates concatenation of strings. 2487 | 2488 | ## Retrying Challenges 2489 | 2490 | ACME challenges typically require the client to set up some network-accessible 2491 | resource that the server can query in order to validate that the client 2492 | controls an identifier. In practice, it is not uncommon for the server's 2493 | queries to fail while a resource is being set up, e.g., due to information 2494 | propagating across a cluster or firewall rules not being in place. 2495 | 2496 | Clients SHOULD NOT respond to challenges until they believe that the server's 2497 | queries will succeed. If a server's initial validation query fails, the server 2498 | SHOULD retry the query after some time, in order to account for delay in setting 2499 | up responses such as DNS records or HTTP resources. The precise retry schedule 2500 | is up to the server, but server operators should keep in mind the operational 2501 | scenarios that the schedule is trying to accommodate. Given that retries are 2502 | intended to address things like propagation delays in HTTP or DNS provisioning, 2503 | there should not usually be any reason to retry more often than every 5 or 10 2504 | seconds. While the server is still trying, the 2505 | status of the challenge remains "processing"; it is only marked "invalid" once the 2506 | server has given up. 2507 | 2508 | The server MUST provide information about its retry state to the client via the 2509 | "error" field in the challenge and the Retry-After HTTP header field in 2510 | response to requests to the challenge resource. The server MUST add an entry to 2511 | the "error" field in the challenge after each failed validation query. The 2512 | server SHOULD set the Retry-After header field to a time after the server's 2513 | next validation query, since the status of the challenge will not change until 2514 | that time. 2515 | 2516 | Clients can explicitly request a retry by re-sending their response to a 2517 | challenge in a new POST request (with a new nonce, etc.). This allows clients 2518 | to request a retry when the state has changed (e.g., after firewall rules have been 2519 | updated). Servers SHOULD retry a request immediately on receiving such a POST 2520 | request. In order to avoid denial-of-service attacks via client-initiated 2521 | retries, servers SHOULD rate-limit such requests. 2522 | 2523 | ## HTTP Challenge 2524 | 2525 | With HTTP validation, the client in an ACME transaction proves its control over 2526 | a domain name by proving that it can provision HTTP resources on a server 2527 | accessible under that domain name. 2528 | The ACME server challenges the client to 2529 | provision a file at a specific path, with a specific string as its content. 2530 | 2531 | As a domain may resolve to multiple IPv4 and IPv6 addresses, the server will 2532 | connect to at least one of the hosts found in the DNS A and AAAA records, at its 2533 | discretion. Because many web servers allocate a default HTTPS virtual host to a 2534 | particular low-privilege tenant user in a subtle and non-intuitive manner, the 2535 | challenge must be completed over HTTP, not HTTPS. 2536 | 2537 | type (required, string): 2538 | : The string "http-01". 2539 | 2540 | token (required, string): 2541 | : A random value that uniquely identifies the challenge. This value MUST have 2542 | at least 128 bits of entropy. 2543 | It MUST NOT contain any characters outside the base64url alphabet and MUST NOT 2544 | include base64 padding characters ("="). See {{!RFC4086}} for additional information 2545 | on randomness requirements. 2546 | 2547 | ~~~~~~~~~~ 2548 | { 2549 | "type": "http-01", 2550 | "url": "https://example.com/acme/chall/prV_B7yEyA4", 2551 | "status": "pending", 2552 | "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" 2553 | } 2554 | ~~~~~~~~~~ 2555 | 2556 | A client fulfills this challenge by constructing a key authorization from 2557 | the "token" value provided in the challenge and the client's account key. The 2558 | client then provisions the key authorization as a resource on the HTTP server 2559 | for the domain in question. 2560 | 2561 | The path at which the resource is provisioned is comprised of the fixed prefix 2562 | "/.well-known/acme-challenge/", followed by the "token" value in the challenge. 2563 | The value of the resource MUST be the ASCII representation of the key 2564 | authorization. 2565 | 2566 | ~~~~~~~~~~ 2567 | GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0 2568 | Host: example.org 2569 | 2570 | HTTP/1.1 200 OK 2571 | Content-Type: application/octet-stream 2572 | 2573 | LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI 2574 | ~~~~~~~~~~ 2575 | 2576 | (In the above, "..." indicates that the token and the JWK 2577 | thumbprint in the key authorization have been truncated to fit on 2578 | the page.) 2579 | 2580 | A client responds with an empty object ({}) to acknowledge that the challenge 2581 | can be validated by the server. 2582 | 2583 | ~~~~~~~~~~ 2584 | POST /acme/chall/prV_B7yEyA4 2585 | Host: example.com 2586 | Content-Type: application/jose+json 2587 | 2588 | { 2589 | "protected": base64url({ 2590 | "alg": "ES256", 2591 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2592 | "nonce": "UQI1PoRi5OuXzxuX7V7wL0", 2593 | "url": "https://example.com/acme/chall/prV_B7yEyA4" 2594 | }), 2595 | "payload": base64url({}), 2596 | "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2597 | } 2598 | ~~~~~~~~~~ 2599 | 2600 | On receiving a response, the server constructs and stores the key authorization 2601 | from the challenge "token" value and the current client account key. 2602 | 2603 | Given a challenge/response pair, the server verifies the client's control of the 2604 | domain by verifying that the resource was provisioned as expected. 2605 | 2606 | 1. Construct a URL by populating the URL template {{!RFC6570}} 2607 | "http://{domain}/.well-known/acme-challenge/{token}", where: 2608 | * the domain field is set to the domain name being verified; and 2609 | * the token field is set to the token in the challenge. 2610 | 2. Verify that the resulting URL is well-formed. 2611 | 3. Dereference the URL using an HTTP GET request. This request MUST be sent to 2612 | TCP port 80 on the HTTP server. 2613 | 4. Verify that the body of the response is a well-formed key authorization. The 2614 | server SHOULD ignore whitespace characters at the end of the body. 2615 | 5. Verify that key authorization provided by the HTTP server matches the key 2616 | authorization stored by the server. 2617 | 2618 | The server SHOULD follow redirects when dereferencing the URL. 2619 | Clients might use redirects, for example, so that the response can 2620 | be provided by a centralized certificate management server. See 2621 | {{integrity-of-authorizations}} for security considerations related 2622 | to redirects. 2623 | 2624 | If all of the above verifications succeed, then the validation is successful. 2625 | If the request fails, or the body does not pass these checks, then it has 2626 | failed. 2627 | 2628 | The client SHOULD de-provision the resource provisioned for this 2629 | challenge once the challenge is complete, i.e., once the "status" 2630 | field of the challenge has the value "valid" or "invalid". 2631 | 2632 | Note that because the token appears both in the request sent by the 2633 | ACME server and in the key authorization in the response, it is 2634 | possible to build clients that copy the token from request to 2635 | response. Clients should avoid this behavior because it can lead 2636 | to cross-site scripting vulnerabilities; instead, clients should be 2637 | explicitly configured on a per-challenge basis. A client that does 2638 | copy tokens from requests to responses MUST validate that the token 2639 | in the request matches the token syntax above (e.g., that it 2640 | includes only characters from the base64url alphabet). 2641 | 2642 | ## DNS Challenge 2643 | 2644 | When the identifier being validated is a domain name, the client can prove 2645 | control of that domain by provisioning a TXT resource record containing a designated 2646 | value for a specific validation domain name. 2647 | 2648 | type (required, string): 2649 | : The string "dns-01". 2650 | 2651 | token (required, string): 2652 | : A random value that uniquely identifies the challenge. This value MUST have 2653 | at least 128 bits of entropy. It MUST NOT contain any characters outside the 2654 | base64url alphabet, including padding characters ("="). See {{!RFC4086}} for 2655 | additional information on randomness requirements. 2656 | 2657 | ~~~~~~~~~~ 2658 | { 2659 | "type": "dns-01", 2660 | "url": "https://example.com/acme/chall/Rg5dV14Gh1Q", 2661 | "status": "pending", 2662 | "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" 2663 | } 2664 | ~~~~~~~~~~ 2665 | 2666 | A client fulfills this challenge by constructing a key authorization from the 2667 | "token" value provided in the challenge and the client's account key. The 2668 | client then computes the SHA-256 digest [FIPS180-4] of the key authorization. 2669 | 2670 | The record provisioned to the DNS contains the base64url encoding of this digest. The 2671 | client constructs the validation domain name by prepending the label 2672 | "\_acme-challenge" to the domain name being validated, then provisions a TXT 2673 | record with the digest value under that name. For example, if the domain name 2674 | being validated is "www.example.org", then the client would provision the following 2675 | DNS record: 2676 | 2677 | ~~~~~~~~~~ 2678 | _acme-challenge.www.example.org. 300 IN TXT "gfj9Xq...Rg85nM" 2679 | ~~~~~~~~~~ 2680 | 2681 | A client responds with an empty object ({}) to acknowledge that the challenge 2682 | can be validated by the server. 2683 | 2684 | ~~~~~~~~~~ 2685 | POST /acme/chall/Rg5dV14Gh1Q 2686 | Host: example.com 2687 | Content-Type: application/jose+json 2688 | 2689 | { 2690 | "protected": base64url({ 2691 | "alg": "ES256", 2692 | "kid": "https://example.com/acme/acct/evOfKhNU60wg", 2693 | "nonce": "SS2sSl1PtspvFZ08kNtzKd", 2694 | "url": "https://example.com/acme/chall/Rg5dV14Gh1Q" 2695 | }), 2696 | "payload": base64url({}), 2697 | "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" 2698 | } 2699 | ~~~~~~~~~~ 2700 | 2701 | On receiving a response, the server constructs and stores the key authorization 2702 | from the challenge "token" value and the current client account key. 2703 | 2704 | To validate a DNS challenge, the server performs the following steps: 2705 | 2706 | 1. Compute the SHA-256 digest [FIPS180-4] of the stored key authorization 2707 | 2. Query for TXT records for the validation domain name 2708 | 3. Verify that the contents of one of the TXT records match the digest value 2709 | 2710 | If all of the above verifications succeed, then the validation is successful. 2711 | If no DNS record is found, or DNS record and response payload do not pass these 2712 | checks, then the validation fails. 2713 | 2714 | The client SHOULD de-provision the resource record(s) provisioned for this 2715 | challenge once the challenge is complete, i.e., once the "status" 2716 | field of the challenge has the value "valid" or "invalid". 2717 | 2718 | # IANA Considerations 2719 | 2720 | ## Media Type: application/pem-certificate-chain 2721 | 2722 | A file of this type contains one or more certificates encoded with 2723 | the PEM textual encoding, according to {{!RFC7468}}. The 2724 | textual encoding of certificates in this file MUST use the strict 2725 | encoding and MUST NOT include explanatory text. The ABNF for this 2726 | format is as follows, where `stricttextualmsg` and `eol` are as 2727 | defined in Section 3 of RFC 7468: 2728 | 2729 | ~~~~~ 2730 | certchain = stricttextualmsg *(eol stricttextualmsg) 2731 | ~~~~~ 2732 | 2733 | In order to provide easy interoperation with TLS, the first 2734 | certificate MUST be an end-entity certificate. Each following certificate 2735 | SHOULD directly certify the one preceding it. Because certificate validation 2736 | requires that trust anchors be distributed independently, a certificate 2737 | that represents a trust anchor MAY be omitted from the chain, provided 2738 | that supported peers are known to possess any omitted certificates. 2739 | 2740 | The following has been registered in the "Media Types" registry: 2741 | 2742 | Type name: application 2743 | 2744 | Subtype name: pem-certificate-chain 2745 | 2746 | Required parameters: None 2747 | 2748 | Optional parameters: None 2749 | 2750 | Encoding considerations: 7bit 2751 | 2752 | Security considerations: Carries a cryptographic certificate and its associated certificate chain. This media type carries no active content. 2753 | 2754 | Interoperability considerations: None 2755 | 2756 | Published specification: RFC 8555 2757 | 2758 | Applications that use this media type: ACME clients and servers, HTTP servers, other applications that need to be configured with a certificate chain 2759 | 2760 | Additional information: 2761 | 2762 | Deprecated alias names for this type: n/a 2763 | Magic number(s): n/a 2764 | File extension(s): .pem 2765 | Macintosh file type code(s): n/a 2766 | 2767 | Person & email address to contact for further information: See Authors' Addresses section. 2768 | 2769 | Intended usage: COMMON 2770 | 2771 | Restrictions on usage: n/a 2772 | 2773 | Author: See Authors' Addresses section. 2774 | 2775 | Change controller: IETF <iesg@ietf.org> 2776 | 2777 | 2778 | ## Well-Known URI for the HTTP Challenge 2779 | 2780 | The following value has been registered in the "Well-Known URIs" registry 2781 | (using the template from {{?RFC5785}}): 2782 | 2783 | URI suffix: acme-challenge 2784 | 2785 | Change controller: IETF 2786 | 2787 | Specification document(s): RFC 8555, {{http-challenge}} 2788 | 2789 | Related information: N/A 2790 | 2791 | ## Replay-Nonce HTTP Header 2792 | 2793 | The following value has been registered in the "Message Headers" 2794 | registry: 2795 | 2796 | | Header Field Name | Protocol | Status | Reference | 2797 | |:------------------|:---------|:---------|:-----------------| 2798 | | Replay-Nonce | http | standard | RFC 8555, {{replay-nonce}} | 2799 | 2800 | ## "url" JWS Header Parameter {#url-jws-header-parameter} 2801 | 2802 | The following value has been registered in the "JSON Web Signature and 2803 | Encryption Header Parameters" registry: 2804 | 2805 | * Header Parameter Name: "url" 2806 | * Header Parameter Description: URL 2807 | * Header Parameter Usage Location(s): JWE, JWS 2808 | * Change Controller: IESG 2809 | * Specification Document(s): RFC 8555, {{url-url-jws-header-parameter}} 2810 | 2811 | ## "nonce" JWS Header Parameter {#nonce-jws-header-parameter} 2812 | 2813 | The following value has been registered in the "JSON Web Signature and 2814 | Encryption Header Parameters" registry: 2815 | 2816 | * Header Parameter Name: "nonce" 2817 | * Header Parameter Description: Nonce 2818 | * Header Parameter Usage Location(s): JWE, JWS 2819 | * Change Controller: IESG 2820 | * Specification Document(s): RFC 8555, {{nonce-nonce-jws-header-parameter}} 2821 | 2822 | ## URN Sub-namespace for ACME (urn:ietf:params:acme) {#acme-urn-space} 2823 | 2824 | The following value has been registered in the "IETF URN Sub-namespace for 2825 | Registered Protocol Parameter Identifiers" registry, following the 2826 | template in {{?RFC3553}}: 2827 | 2828 | Registry name: 2829 | : acme 2830 | 2831 | Specification: 2832 | : RFC 8555 2833 | 2834 | Repository: 2835 | : http://www.iana.org/assignments/acme 2836 | 2837 | Index value: 2838 | : No transformation needed. 2839 | 2840 | ## New Registries 2841 | 2842 | IANA has created the following registries: 2843 | 2844 | 1. ACME Account Object Fields ({{iana-account}}) 2845 | 2. ACME Order Object Fields ({{iana-order}}) 2846 | 3. ACME Authorization Object Fields ({{iana-authz}}) 2847 | 4. ACME Error Types ({{iana-error}}) 2848 | 5. ACME Resource Types ({{iana-resource}}) 2849 | 6. ACME Directory Metadata Fields ({{iana-meta}}) 2850 | 7. ACME Identifier Types ({{iana-identifier}}) 2851 | 8. ACME Validation Methods ({{iana-validation}}) 2852 | 2853 | All of these registries are under a heading of "Automated Certificate Management 2854 | Environment (ACME) Protocol" and are administered under a Specification 2855 | Required policy {{!RFC8126}}. 2856 | 2857 | ### Fields in Account Objects {#iana-account} 2858 | 2859 | The "ACME Account Object Fields" registry lists field names that are defined 2860 | for use in ACME account objects. Fields marked as "configurable" may be included in a 2861 | newAccount request. 2862 | 2863 | Template: 2864 | 2865 | * Field name: The string to be used as a field name in the JSON object 2866 | * Field type: The type of value to be provided, e.g., string, boolean, array of 2867 | string 2868 | * Requests: Either the value "none" or a list of types of requests 2869 | where the field is allowed in a request object, taken from the 2870 | following values: 2871 | * "new" - Requests to the "newAccount" URL 2872 | * "account" - Requests to an account URL 2873 | * Reference: Where this field is defined 2874 | 2875 | Initial contents: The fields and descriptions defined in {{account-objects}}. 2876 | 2877 | | Field Name | Field Type | Requests | Reference | 2878 | |:-------------------------|:----------------|:-------------|:----------| 2879 | | status | string | new, account | RFC 8555 | 2880 | | contact | array of string | new, account | RFC 8555 | 2881 | | externalAccountBinding | object | new | RFC 8555 | 2882 | | termsOfServiceAgreed | boolean | new | RFC 8555 | 2883 | | onlyReturnExisting | boolean | new | RFC 8555 | 2884 | | orders | string | none | RFC 8555 | 2885 | 2886 | ### Fields in Order Objects {#iana-order} 2887 | 2888 | The "ACME Order Object Fields" registry lists field names that are defined 2889 | for use in ACME order objects. Fields marked as "configurable" may be included in a 2890 | newOrder request. 2891 | 2892 | Template: 2893 | 2894 | * Field name: The string to be used as a field name in the JSON object 2895 | * Field type: The type of value to be provided, e.g., string, boolean, array of 2896 | string 2897 | * Configurable: Boolean indicating whether the server should accept 2898 | values provided by the client 2899 | * Reference: Where this field is defined 2900 | 2901 | Initial contents: The fields and descriptions defined in {{order-objects}}. 2902 | 2903 | | Field Name | Field Type | Configurable | Reference | 2904 | |:---------------|:---------------------|:-------------|:----------| 2905 | | status | string | false | RFC 8555 | 2906 | | expires | string | false | RFC 8555 | 2907 | | identifiers | array of object | true | RFC 8555 | 2908 | | notBefore | string | true | RFC 8555 | 2909 | | notAfter | string | true | RFC 8555 | 2910 | | error | string | false | RFC 8555 | 2911 | | authorizations | array of string | false | RFC 8555 | 2912 | | finalize | string | false | RFC 8555 | 2913 | | certificate | string | false | RFC 8555 | 2914 | 2915 | ### Fields in Authorization Objects {#iana-authz} 2916 | 2917 | The "ACME Authorization Object Fields" registry lists field names that are 2918 | defined for use in ACME authorization objects. Fields marked as 2919 | "configurable" may be included in a newAuthz request. 2920 | 2921 | Template: 2922 | 2923 | * Field name: The string to be used as a field name in the JSON object 2924 | * Field type: The type of value to be provided, e.g., string, boolean, array of 2925 | string 2926 | * Configurable: Boolean indicating whether the server should accept 2927 | values provided by the client 2928 | * Reference: Where this field is defined 2929 | 2930 | Initial contents: The fields and descriptions defined in {{authorization-objects}}. 2931 | 2932 | | Field Name | Field Type | Configurable | Reference | 2933 | |:------------|:----------------|:-------------|:----------| 2934 | | identifier | object | true | RFC 8555 | 2935 | | status | string | false | RFC 8555 | 2936 | | expires | string | false | RFC 8555 | 2937 | | challenges | array of object | false | RFC 8555 | 2938 | | wildcard | boolean | false | RFC 8555 | 2939 | 2940 | ### Error Types {#iana-error} 2941 | 2942 | The "ACME Error Types" registry lists values that are used within URN 2943 | values that are provided in the "type" field of problem documents in ACME. 2944 | 2945 | Template: 2946 | 2947 | * Type: The label to be included in the URN for this error, following 2948 | "urn:ietf:params:acme:error:" 2949 | * Description: A human-readable description of the error 2950 | * Reference: Where the error is defined 2951 | 2952 | Initial contents: The types and descriptions in the table in {{errors}} above, 2953 | with the Reference field set to point to this specification. 2954 | 2955 | ### Resource Types {#iana-resource} 2956 | 2957 | The "ACME Resource Types" registry lists the types of resources that ACME 2958 | servers may list in their directory objects. 2959 | 2960 | Template: 2961 | 2962 | * Field name: The value to be used as a field name in the directory object 2963 | * Resource type: The type of resource labeled by the field 2964 | * Reference: Where the resource type is defined 2965 | 2966 | Initial contents: 2967 | 2968 | | Field Name | Resource Type | Reference | 2969 | |:---------------|:---------------------|:----------| 2970 | | newNonce | New nonce | RFC 8555 | 2971 | | newAccount | New account | RFC 8555 | 2972 | | newOrder | New order | RFC 8555 | 2973 | | newAuthz | New authorization | RFC 8555 | 2974 | | revokeCert | Revoke certificate | RFC 8555 | 2975 | | keyChange | Key change | RFC 8555 | 2976 | | meta | Metadata object | RFC 8555 | 2977 | 2978 | ### Fields in the "meta" Object within a Directory Object {#iana-meta} 2979 | 2980 | The "ACME Directory Metadata Fields" registry lists field names that are 2981 | defined for use in the JSON object included in the "meta" field of an ACME 2982 | directory object. 2983 | 2984 | Template: 2985 | 2986 | * Field name: The string to be used as a field name in the JSON object 2987 | * Field type: The type of value to be provided, e.g., string, boolean, array of 2988 | string 2989 | * Reference: Where this field is defined 2990 | 2991 | Initial contents: The fields and descriptions defined in {{directory}}. 2992 | 2993 | | Field Name | Field Type | Reference | 2994 | |:------------------------|:----------------|:----------| 2995 | | termsOfService | string | RFC 8555 | 2996 | | website | string | RFC 8555 | 2997 | | caaIdentities | array of string | RFC 8555 | 2998 | | externalAccountRequired | boolean | RFC 8555 | 2999 | 3000 | ### Identifier Types {#iana-identifier} 3001 | 3002 | The "ACME Identifier Types" registry lists the types of identifiers that 3003 | can be present in ACME authorization objects. 3004 | 3005 | Template: 3006 | 3007 | * Label: The value to be put in the "type" field of the identifier object 3008 | * Reference: Where the identifier type is defined 3009 | 3010 | Initial contents: 3011 | 3012 | | Label | Reference | 3013 | |:------|:----------| 3014 | | dns | RFC 8555 | 3015 | 3016 | ### Validation Methods {#iana-validation} 3017 | 3018 | The "ACME Validation Methods" registry lists identifiers for the ways that 3019 | CAs can validate control of identifiers. Each method's entry must specify 3020 | whether it corresponds to an ACME challenge type. The "Identifier Type" field 3021 | must be contained in the Label column of the "ACME Identifier Types" registry. 3022 | 3023 | Template: 3024 | 3025 | * Label: The identifier for this validation method 3026 | * Identifier Type: The type of identifier that this method applies to 3027 | * ACME: "Y" if the validation method corresponds to an ACME challenge type; 3028 | "N" otherwise 3029 | * Reference: Where the validation method is defined 3030 | 3031 | This registry may also contain reserved entries (e.g., to avoid 3032 | collisions). Such entries should have the "ACME" field set to "N" 3033 | and the "Identifier Type" set to "RESERVED". 3034 | 3035 | Initial Contents 3036 | 3037 | | Label | Identifier Type | ACME | Reference | 3038 | |:-----------|:----------------|:-----|:----------| 3039 | | http-01 | dns | Y | RFC 8555 | 3040 | | dns-01 | dns | Y | RFC 8555 | 3041 | | tls-sni-01 | RESERVED | N | RFC 8555 | 3042 | | tls-sni-02 | RESERVED | N | RFC 8555 | 3043 | 3044 | When evaluating a request for an assignment in this registry, the designated 3045 | expert should ensure that the method being registered has a clear, 3046 | interoperable definition and does not overlap with existing validation methods. 3047 | That is, it should not be possible for a client and server to follow the 3048 | same set of actions to fulfill two different validation methods. 3049 | 3050 | The values "tls-sni-01" and "tls-sni-02" are reserved because they 3051 | were used in pre-RFC versions of this specification to denote 3052 | validation methods that were removed because they were found not to be secure in some cases. 3053 | 3054 | Validation methods do not have to be compatible with ACME in order to be 3055 | registered. For example, a CA might wish to register a validation method 3056 | to support its use with the ACME extensions to CAA 3057 | {{?I-D.ietf-acme-caa}}. 3058 | 3059 | # Security Considerations 3060 | 3061 | ACME is a protocol for managing certificates that attest to identifier/key 3062 | bindings. Thus, the foremost security goal of ACME is to ensure the integrity of 3063 | this process, i.e., to ensure that the bindings attested by certificates are 3064 | correct and that only authorized entities can manage certificates. ACME 3065 | identifies clients by their account keys, so this overall goal breaks down into 3066 | two more precise goals: 3067 | 3068 | 1. Only an entity that controls an identifier can get an authorization for that 3069 | identifier 3070 | 2. Once authorized, an account key's authorizations cannot be improperly 3071 | used by another account 3072 | 3073 | In this section, we discuss the threat model that underlies ACME and the ways 3074 | that ACME achieves these security goals within that threat model. We also 3075 | discuss the denial-of-service risks that ACME servers face, and a few other 3076 | miscellaneous considerations. 3077 | 3078 | ## Threat Model 3079 | 3080 | As a service on the Internet, ACME broadly exists within the Internet threat 3081 | model {{?RFC3552}}. In analyzing ACME, it is useful to think of an ACME server 3082 | interacting with other Internet hosts along two "channels": 3083 | 3084 | * An ACME channel, over which the ACME HTTPS requests are exchanged 3085 | * A validation channel, over which the ACME server performs additional requests 3086 | to validate a client's control of an identifier 3087 | 3088 | ~~~~~~~~~~ 3089 | +------------+ 3090 | | ACME | ACME Channel 3091 | | Client |--------------------+ 3092 | +------------+ | 3093 | V 3094 | +------------+ 3095 | | ACME | 3096 | | Server | 3097 | +------------+ 3098 | +------------+ | 3099 | | Validation |<-------------------+ 3100 | | Server | Validation Channel 3101 | +------------+ 3102 | ~~~~~~~~~~ 3103 | {: title="Communications Channels Used by ACME"} 3104 | 3105 | In practice, the risks to these channels are not entirely separate, but they are 3106 | different in most cases. Each channel, for example, uses a 3107 | different communications pattern: the ACME channel will comprise inbound HTTPS 3108 | connections to the ACME server and the validation channel outbound HTTP or DNS 3109 | requests. 3110 | 3111 | Broadly speaking, ACME aims to be secure against active and passive attackers on 3112 | any individual channel. Some vulnerabilities arise (noted below) when an 3113 | attacker can exploit both the ACME channel and one of the others. 3114 | 3115 | On the ACME channel, in addition to network-layer attackers, we also need to 3116 | account for man-in-the-middle (MitM) attacks at the application layer and for 3117 | abusive use of the protocol itself. Protection against application-layer MitM 3118 | addresses potential attackers such as Content Distribution Networks (CDNs) and 3119 | middleboxes with a TLS MitM function. Preventing abusive use of ACME means 3120 | ensuring that an attacker with access to the validation channel can't obtain 3121 | illegitimate authorization by acting as an ACME client (legitimately, in terms 3122 | of the protocol). 3123 | 3124 | ACME does not protect against other types of abuse by a MitM on the ACME channel. 3125 | For example, such an attacker could send a bogus "badSignatureAlgorithm" 3126 | error response to downgrade a client to the lowest-quality signature algorithm that 3127 | the server supports. A MitM that is present on all connections (such as a 3128 | CDN) can cause denial-of-service conditions in a variety of ways. 3129 | 3130 | ## Integrity of Authorizations 3131 | 3132 | ACME allows anyone to request challenges for an identifier by registering an 3133 | account key and sending a newOrder request using that account key. The 3134 | integrity of the authorization process thus depends on the identifier validation 3135 | challenges to ensure that the challenge can only be completed by someone who 3136 | both (1) holds the private key of the account key pair and (2) controls the 3137 | identifier in question. 3138 | 3139 | Validation responses need to be bound to an account key pair in order to avoid 3140 | situations where a MitM on ACME HTTPS requests can switch out a legitimate domain holder's 3141 | account key for one of his choosing. Such MitMs can arise, for 3142 | example, if a CA uses a CDN or third-party reverse proxy in front of 3143 | its ACME interface. An attack by such an MitM could have the 3144 | following form: 3145 | 3146 | 1. Legitimate domain holder registers account key pair A 3147 | 2. MitM registers account key pair B 3148 | 3. Legitimate domain holder sends a newOrder request signed using account key A 3149 | 4. MitM suppresses the legitimate request but sends the same request signed 3150 | using account key B 3151 | 5. ACME server issues challenges and MitM forwards them to the legitimate domain 3152 | holder 3153 | 6. Legitimate domain holder provisions the validation response 3154 | 7. ACME server performs validation query and sees the response provisioned by the 3155 | legitimate domain holder 3156 | 8. Because the challenges were issued in response to a message signed with account key 3157 | B, the ACME server grants authorization to account key B (the MitM) instead of 3158 | account key A (the legitimate domain holder) 3159 | 3160 | ~~~~~ 3161 | Domain ACME 3162 | Holder MitM Server 3163 | | | | 3164 | | newAccount(A) | | 3165 | |--------------------->|--------------------->| 3166 | | | | 3167 | | | newAccount(B) | 3168 | | |--------------------->| 3169 | | newOrder(domain, A) | | 3170 | |--------------------->| | 3171 | | | newOrder(domain, B) | 3172 | | |--------------------->| 3173 | | | | 3174 | | authz, challenges | authz, challenges | 3175 | |<---------------------|<---------------------| 3176 | | | | 3177 | | response(chall, A) | response(chall, B) | 3178 | |--------------------->|--------------------->| 3179 | | | | 3180 | | validation request | | 3181 | |<--------------------------------------------| 3182 | | | | 3183 | | validation response | | 3184 | |-------------------------------------------->| 3185 | | | | 3186 | | | | Considers challenge 3187 | | | | fulfilled by B 3188 | | | | 3189 | ~~~~~ 3190 | {: title="Man-in-the-Middle Attack Exploiting a Validation Method without 3191 | Account Key Binding"} 3192 | 3193 | All of the challenges defined in this document have a binding between the account private key and 3194 | the validation query made by the server, via the key authorization. The key 3195 | authorization reflects the account public key and is provided to the server in 3196 | the validation response over the validation channel. 3197 | 3198 | The association of challenges to identifiers is typically done by requiring the 3199 | client to perform some action that only someone who effectively controls the 3200 | identifier can perform. For the challenges in this document, the actions are as follows: 3201 | 3202 | * HTTP: Provision files under .well-known on a web server for the domain 3203 | * DNS: Provision DNS resource records for the domain 3204 | 3205 | There are several ways that these assumptions can be violated, both by 3206 | misconfiguration and by attacks. For example, on a web server that allows 3207 | non-administrative users to write to .well-known, any user can claim to own the 3208 | web server's hostname by responding to an HTTP challenge. Similarly, if 3209 | a server that can be used for ACME 3210 | validation is compromised by a malicious actor, then that malicious actor can 3211 | use that access to obtain certificates via ACME. 3212 | 3213 | The use of hosting providers is a particular risk for ACME validation. If the 3214 | owner of the domain has outsourced operation of DNS or web services to a hosting 3215 | provider, there is nothing that can be done against tampering by the hosting 3216 | provider. As far as the outside world is concerned, the zone or website 3217 | provided by the hosting provider is the real thing. 3218 | 3219 | More limited forms of delegation can also lead to an unintended party gaining 3220 | the ability to successfully complete a validation transaction. For example, 3221 | suppose an ACME server follows HTTP redirects in HTTP validation and a 3222 | website operator provisions a catch-all redirect rule that redirects requests 3223 | for unknown resources to a different domain. Then the target of the redirect 3224 | could use that to get a certificate through HTTP validation since the 3225 | validation path will not be known to the primary server. 3226 | 3227 | The DNS is a common point of vulnerability for all of these challenges. An 3228 | entity that can provision false DNS records for a domain can attack the DNS 3229 | challenge directly and can provision false A/AAAA records to direct the ACME 3230 | server to send its HTTP validation query to a remote server of the attacker's 3231 | choosing. There are a few different mitigations that ACME servers 3232 | can apply: 3233 | 3234 | * Always querying the DNS using a DNSSEC-validating resolver (enhancing 3235 | security for zones that are DNSSEC-enabled) 3236 | * Querying the DNS from multiple vantage points to address local attackers 3237 | * Applying mitigations against DNS off-path attackers, e.g., adding entropy to 3238 | requests {{?I-D.vixie-dnsext-dns0x20}} or only using TCP 3239 | 3240 | Given these considerations, the ACME validation process makes it impossible for 3241 | any attacker on the ACME channel or a passive attacker on the validation 3242 | channel to hijack the authorization process to authorize a key of the attacker's 3243 | choice. 3244 | 3245 | An attacker that can only see the ACME channel would need to convince the 3246 | validation server to provide a response that would authorize the attacker's 3247 | account key, but this is prevented by binding the validation response to the 3248 | account key used to request challenges. A passive attacker on the validation 3249 | channel can observe the correct validation response and even replay it, but that 3250 | response can only be used with the account key for which it was generated. 3251 | 3252 | An active attacker on the validation channel can subvert the ACME process, by 3253 | performing normal ACME transactions and providing a validation response for his 3254 | own account key. The risks due to hosting providers noted above are a 3255 | particular case. 3256 | 3257 | Attackers can also exploit vulnerabilities in Internet routing 3258 | protocols to gain access to the validation channel (see, e.g., 3259 | {{?RFC7132}}). In order to make such attacks more difficult, it is 3260 | RECOMMENDED that the server perform DNS queries and make HTTP 3261 | connections from multiple points in the network. Since routing 3262 | attacks are often localized or dependent on the position of the 3263 | attacker, forcing the attacker to attack multiple points (the 3264 | server's validation vantage points) or a specific point (the DNS / HTTP server) makes it more difficult to subvert ACME validation 3265 | using attacks on routing. 3266 | 3267 | ## Denial-of-Service Considerations 3268 | 3269 | As a protocol run over HTTPS, standard considerations for TCP-based and 3270 | HTTP-based DoS mitigation also apply to ACME. 3271 | 3272 | At the application layer, ACME requires the server to perform a few potentially 3273 | expensive operations. Identifier validation transactions require the ACME 3274 | server to make outbound connections to potentially attacker-controlled servers, 3275 | and certificate issuance can require interactions with cryptographic hardware. 3276 | 3277 | In addition, an attacker can also cause the ACME server to send validation 3278 | requests to a domain of its choosing by submitting authorization requests for 3279 | the victim domain. 3280 | 3281 | All of these attacks can be mitigated by the application of appropriate rate 3282 | limits. Issues closer to the front end, like POST body validation, can be 3283 | addressed using HTTP request limiting. For validation and certificate requests, 3284 | there are other identifiers on which rate limits can be keyed. For example, the 3285 | server might limit the rate at which any individual account key can issue 3286 | certificates or the rate at which validation can be requested within a given 3287 | subtree of the DNS. And in order to prevent attackers from circumventing these 3288 | limits simply by minting new accounts, servers would need to limit the rate at 3289 | which accounts can be registered. 3290 | 3291 | ## Server-Side Request Forgery 3292 | 3293 | Server-Side Request Forgery (SSRF) attacks can arise when an attacker can cause 3294 | a server to perform HTTP requests to an attacker-chosen URL. In the ACME HTTP 3295 | challenge validation process, the ACME server performs an HTTP GET request to a 3296 | URL in which the attacker can choose the domain. This request is made before 3297 | the server has verified that the client controls the domain, so any client can 3298 | cause a query to any domain. 3299 | 3300 | Some ACME server implementations include information from the validation server's 3301 | response (in order to facilitate debugging). Such implementations enable an 3302 | attacker to extract this information from any web server that is accessible to 3303 | the ACME server, even if it is not accessible to the ACME client. 3304 | For example, the ACME server might be able to access servers behind 3305 | a firewall that would prevent access by the ACME client. 3306 | 3307 | It might seem that the risk of SSRF through this channel is limited by the fact 3308 | that the attacker can only control the domain of the URL, not the path. 3309 | However, if the attacker first sets the domain to one they control, then they 3310 | can send the server an HTTP redirect (e.g., a 302 response) which will cause the 3311 | server to query an arbitrary URL. 3312 | 3313 | In order to further limit the SSRF risk, ACME server operators should ensure 3314 | that validation queries can only be sent to servers on the public Internet, and 3315 | not, say, web services within the server operator's internal network. Since the 3316 | attacker could make requests to these public servers himself, he can't gain 3317 | anything extra through an SSRF attack on ACME aside from a layer of 3318 | anonymization. 3319 | 3320 | ## CA Policy Considerations 3321 | 3322 | The controls on issuance enabled by ACME are focused on validating that a 3323 | certificate applicant controls the identifier he claims. Before issuing a 3324 | certificate, however, there are many other checks that a CA might need to 3325 | perform, for example: 3326 | 3327 | * Has the client agreed to a subscriber agreement? 3328 | * Is the claimed identifier syntactically valid? 3329 | * For domain names: 3330 | * If the leftmost label is a '\*', then have the appropriate checks been 3331 | applied? 3332 | * Is the name on the Public Suffix List? 3333 | * Is the name a high-value name? 3334 | * Is the name a known phishing domain? 3335 | * Is the key in the CSR sufficiently strong? 3336 | * Is the CSR signed with an acceptable algorithm? 3337 | * Has issuance been authorized or forbidden by a Certificate Authority 3338 | Authorization (CAA) record ({{?RFC6844}})? 3339 | 3340 | CAs that use ACME to automate issuance will need to ensure that their servers 3341 | perform all necessary checks before issuing. 3342 | 3343 | CAs using ACME to allow clients to agree to terms of service should keep in mind 3344 | that ACME clients can automate this agreement, possibly not involving a human 3345 | user. 3346 | 3347 | ACME does not specify how the server constructs the URLs that it 3348 | uses to address resources. If the server operator uses URLs that 3349 | are predictable to third parties, this can leak information about 3350 | what URLs exist on the server, since an attacker can probe for 3351 | whether a POST-as-GET request to the URL returns 404 (Not Found) or 3352 | 401 (Unauthorized). 3353 | 3354 | For example, suppose that the CA uses highly structured URLs with 3355 | guessable fields: 3356 | 3357 | * Accounts: https://example.com/:accountID 3358 | * Orders: https://example.com/:accountID/:domainName 3359 | * Authorizations: https://example.com/:accountID/:domainName 3360 | * Certificates: https://example.com/:accountID/:domainName 3361 | 3362 | Under that scheme, an attacker could probe for which domain names are 3363 | associated with which accounts, which may allow correlation of ownership 3364 | between domain names, if the CA does not otherwise permit it. 3365 | 3366 | To avoid leaking these correlations, CAs SHOULD assign URLs with an 3367 | unpredictable component. 3368 | For example, a CA might assign URLs for each resource type from an 3369 | independent namespace, using unpredictable IDs for each resource: 3370 | 3371 | * Accounts: https://example.com/acct/:accountID 3372 | * Orders: https://example.com/order/:orderID 3373 | * Authorizations: https://example.com/authz/:authorizationID 3374 | * Certificates: https://example.com/cert/:certID 3375 | 3376 | Such a scheme would leak only the type of resource, hiding the 3377 | additional correlations revealed in the example above. 3378 | 3379 | # Operational Considerations 3380 | 3381 | There are certain factors that arise in operational reality that operators of 3382 | ACME-based CAs will need to keep in mind when configuring their services. 3383 | See the subsections below for examples. 3384 | 3385 | ## Key Selection 3386 | 3387 | ACME relies on two different classes of key pair: 3388 | 3389 | * Account key pairs, which are used to authenticate account holders 3390 | * Certificate key pairs, which are used to sign and verify CSRs (and whose 3391 | public keys are included in certificates) 3392 | 3393 | Compromise of the private key of an account key pair has more serious consequences than 3394 | compromise of a private key corresponding to a certificate. While 3395 | the compromise of a certificate key pair allows the attacker to impersonate the 3396 | entities named in the certificate for the lifetime of the certificate, the 3397 | compromise of an account key pair allows the attacker to take full control of 3398 | the victim's ACME account and take any action that the legitimate 3399 | account holder could take within the scope of ACME: 3400 | 3401 | 1. Issuing certificates using existing authorizations 3402 | 2. Revoking existing certificates 3403 | 3. Accessing and changing account information (e.g., contacts) 3404 | 4. Changing the account key pair for the account, locking out the 3405 | legitimate account holder 3406 | 3407 | For this reason, it is RECOMMENDED that each account key pair be 3408 | used only for authentication of a single ACME account. For example, 3409 | the public key of an account key pair MUST NOT be included in a 3410 | certificate. If an ACME client receives a request from a user for 3411 | account creation or key rollover using an account key that the 3412 | client knows to be used elsewhere, then the client MUST return an 3413 | error. Clients MUST generate a fresh account key for every account 3414 | creation or rollover operation. Note that given the requirements of 3415 | {{finding-an-account-url-given-a-key}}, servers will not create 3416 | accounts with reused keys anyway. 3417 | 3418 | ACME clients and servers MUST verify that a CSR submitted in a finalize request does not contain a 3419 | public key for any known account key pair. In particular, when a server 3420 | receives a finalize request, it MUST verify that the public key in a CSR is not 3421 | the same as the public key of the account key pair used to authenticate that 3422 | request. This assures that vulnerabilities in the protocols with which the 3423 | certificate is used (e.g., signing oracles in TLS [JSS15]) do not result in 3424 | compromise of the ACME account. Because ACME accounts are uniquely identified by 3425 | their account key pair (see {{finding-an-account-url-given-a-key}}), the server 3426 | MUST not allow account key pair reuse across multiple accounts. 3427 | 3428 | ## DNS Security 3429 | 3430 | As noted above, DNS forgery attacks against the ACME server can result in the 3431 | server making incorrect decisions about domain control and thus mis-issuing 3432 | certificates. Servers SHOULD perform DNS queries over TCP, which provides better 3433 | resistance to some forgery attacks than DNS over UDP. 3434 | 3435 | An ACME-based CA will often need to make DNS queries, e.g., to validate control 3436 | of DNS names. Because the security of such validations ultimately depends on 3437 | the authenticity of DNS data, every possible precaution should be taken to 3438 | secure DNS queries done by the CA. Therefore, it is RECOMMENDED that ACME-based 3439 | CAs make all DNS queries via DNSSEC-validating stub or recursive resolvers. This 3440 | provides additional protection to domains that choose to make use of DNSSEC. 3441 | 3442 | An ACME-based CA must only use a resolver if it trusts the resolver and every 3443 | component of the network route by which it is accessed. Therefore, it is 3444 | RECOMMENDED that ACME-based CAs operate their own DNSSEC-validating resolvers 3445 | within their trusted network and use these resolvers both for CAA record 3446 | lookups and all record lookups in furtherance of a challenge scheme (A, AAAA, 3447 | TXT, etc.). 3448 | 3449 | ## Token Entropy 3450 | 3451 | The http-01 and dns-01 validation methods mandate the use of 3452 | a random token value to uniquely identify the challenge. The value of the token 3453 | is required to contain at least 128 bits of entropy for the following security 3454 | properties. First, the ACME client should not be able to influence the ACME 3455 | server's choice of token as this may allow an attacker to reuse a domain owner's 3456 | previous challenge responses for a new validation request. Second, the entropy 3457 | requirement makes it more difficult for ACME clients to implement a "naive" 3458 | validation server that automatically replies to challenges without being 3459 | configured per challenge. 3460 | 3461 | ## Malformed Certificate Chains 3462 | 3463 | ACME provides certificate chains in the widely used format known colloquially 3464 | as PEM (though it may diverge from the actual Privacy Enhanced Mail 3465 | specification {{?RFC1421}}, as noted in {{RFC7468}}). Some current software 3466 | will allow the configuration of a private key and a certificate in one PEM 3467 | file by concatenating the textual encodings of the two objects. In the context 3468 | of ACME, such software might be vulnerable to key replacement attacks. A 3469 | malicious ACME server could cause a client to use a private key of its choosing 3470 | by including the key in the PEM file returned in response to a query for a 3471 | certificate URL. 3472 | 3473 | When processing a file of type "application/pem-certificate-chain", a client 3474 | SHOULD verify that the file contains only encoded certificates. If anything 3475 | other than a certificate is found (i.e., if the string "\-\-\-\-\-BEGIN" is ever 3476 | followed by anything other than "CERTIFICATE"), then the client MUST reject the 3477 | file as invalid. 3478 | 3479 | # Acknowledgements 3480 | 3481 | In addition to the editors listed on the front page, this document has benefited 3482 | from contributions from a broad set of contributors, all the way back to its 3483 | inception. 3484 | 3485 | * Andrew Ayer, SSLMate 3486 | * Karthik Bhargavan, INRIA 3487 | * Peter Eckersley, EFF 3488 | * Alex Halderman, University of Michigan 3489 | * Sophie Herold, Hemio 3490 | * Tim Hollebeek, DigiCert 3491 | * Eric Rescorla, Mozilla 3492 | * Seth Schoen, EFF 3493 | * Roland Shoemaker, Let's Encrypt 3494 | * Rob Stradling, Sectigo 3495 | * Martin Thomson, Mozilla 3496 | * Jakub Warmuz, University of Oxford 3497 | 3498 | This document draws on many concepts established by Eric Rescorla's "Automated 3499 | Certificate Issuance Protocol" draft. Martin Thomson provided helpful guidance 3500 | in the use of HTTP. 3501 | -------------------------------------------------------------------------------- /rfced/clean-xml.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: utf-8 -*- 3 | 4 | import re 5 | import sys 6 | 7 | md_skip = False 8 | rfced_remove = False 9 | for line in sys.stdin: 10 | # Strip newline 11 | line = line.rstrip() 12 | 13 | # Strip the kramdown-rfc2629 attribution line 14 | if re.search(r'', line) 38 | continue 39 | 40 | # Strip the kramdown-rfc2629 credit 41 | if re.match(r'