@@ -37,7 +37,7 @@ to get openssl and echo working on Windows.
3737
3838## How this website works
3939
40- This website works by making requests to the Let's Encrypt [ API] ( https://acme-v01 .api.letsencrypt.org )
40+ This website works by making requests to the Let's Encrypt [ API] ( https://acme-v02 .api.letsencrypt.org/directory )
4141(using the [ ACME] ( https://github.com/ietf-wg-acme/acme ) protocol). There's 5 steps to the process,
4242which are explained below. Also, I encourage you to read the source code (it's not that long) and
4343pop open your browser's debugger to see the ajax requests that are going on. Please, audit this!
@@ -90,21 +90,19 @@ cannot be the same as your account private key, according to ACME.
9090
9191### Step 3: Sign API Requests
9292
93- Third, you need tell the Let's Encrypt API that you want to register and get certs
94- for some domains. These requests must be signed with your account private key, so
95- this steps compiles the request payloads that need signatures. You need to ask for
96- challenges for each domain, so if you want both ` example.com ` and ` www.example.com ` , you
97- need to make two new-authz calls.
93+ Third, you need tell the Let's Encrypt API that you want to register and create an order
94+ for a certificate (your CSR). These requests must be signed with your account private key, so
95+ this steps compiles the request payloads that need signatures to get the domain challenges
96+ you need to fulfill.
9897
9998Here's the list of requests that need to be made to the API:
10099
101- * ` /acme/new-reg ` - Register the account public key (discarded if already registered)
102- * ` /acme/new-authz ` - Asks for challenges for the domain for which you want a cert.
103- * ` /acme/new-authz ` - (...needs to be called for each domain)
104- * ` /acme/new-cert ` - Asking for your CSR to be signed.
100+ * ` /acme/new-acct ` - Register the account public key and accept the terms (discarded if already registered)
101+ * ` /acme/acct/... ` - Update the account with your email address
102+ * ` /acme/new-order ` - Creates a new order for a certificate for your domains in your CSR
105103
106104NOTE: Each request also requires an anti-replay nonce, so the javascript gets
107- those by making ajax requests to the ` /directory ` endpoint.
105+ those by making ajax requests to the ` /acme/new-nonce ` endpoint.
108106
109107For each request the payload must be signed, and since this website doesn't ask
110108for your private keys, you must copy-and-paste the signature commands into your
@@ -118,38 +116,40 @@ PRIV_KEY=./account.key; \ #set the location of your account
118116```
119117
120118Once these signatures are pasted back into the inputs, the javascript makes the
121- ajax requests to the above endpoints for ` new-reg ` and each ` new-authz ` . If the
122- account public key has already been registered the ` new-reg ` response is a 409
123- Conflict , which is ignored.
119+ ajax requests to the above endpoints for ` new-acct ` and each ` new-order ` . If the
120+ account public key has already been registered the ` new-acct ` response is a 204
121+ No Content , which is ignored.
124122
125123### Step 4: Verify Ownership
126124
127- The response for each ` /new-authz ` has some challenges you need perform to
128- prove you own the domain. The challenge that this website chooses is "http-01",
129- which requires that you host a specific file at a specific location. So, for
125+ The response for the ` /new-order ` has links to the authorization challenges needed
126+ prove you own the domain. The challenge that this website chooses is "http-01" or
127+ "dns-01", which requires that you host a specific file at a specific location
128+ or set a specific TXT value in your DNS for that domain. So, for
130129each domain, this step shows you the file you need to host and the url you need
131130to host it at.
132131
133132After the file is being hosted, you need to tell Let's Encrypt to check the
134133verify the challenge for that domain. That request must also be signed so
135134there's one more signature that must be performed. The reason why this wasn't
136135included in step 3 is because the payload contains something in the response of
137- ` /new-authz ` .
136+ ` /new-order ` .
138137
139- There's two options this website offers as copy-and-paste commands: python and
140- file-based . The python command is a mini server you can copy-and-paste into your
138+ There's three options this website offers as copy-and-paste commands: python, file-based,
139+ and dns . The python command is a mini server you can copy-and-paste into your
141140server's command line (NOTE: this needs sudo permissions!). The file-base option
142141just lists the url where the challenge will check and the file contents that the
143- file needs to contain. It's up to you to figure out how to make that happen.
142+ file needs to contain. The DNS option lists the value you need to set as a TXT
143+ entry in your DNS. It's up to you to figure out how to make that happen.
144144
145145When you confirm that you're hosting the files, an ajax request is made to the
146146challenge url to tell Let's Encrypt to verify the domain. Once this is done for
147- all the domains in your CSR, an ajax request is made to ` /new-cert ` with the
148- previously signed payload from step 3 .
147+ all the domains in your CSR, the final signature is to finalize the order and
148+ sign your certificate .
149149
150150### Step 5: Install Certificate
151151
152- The response from ` /new-cert ` should be your new certificate! Congrats! This
152+ The response from finalizing should be your new certificate! Congrats! This
153153step prints the certificate and also prints the intermediate certificate you
154154need to chain this certificate to the root certificate.
155155
@@ -172,7 +172,6 @@ feel free to read through it! I tried to comment things well and make it crystal
172172clear what it's doing.
173173
174174TODO (pull requests welcome):
175- * ` renew.html ` - A page with steps for renewing certificates
176175* ` revoke.html ` - A page with steps for revoking certificates
177176* ~~ Alternative file-based command instead of python server~~
178177* ~~ Installation instructions for Apache~~
0 commit comments