Skip to content

Commit 060a2d4

Browse files
committed
moved from beta v2 to full release v2
1 parent c881969 commit 060a2d4

5 files changed

Lines changed: 1555 additions & 2952 deletions

File tree

README.md

Lines changed: 24 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -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,
4242
which are explained below. Also, I encourage you to read the source code (it's not that long) and
4343
pop 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

9998
Here'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

106104
NOTE: 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

109107
For each request the payload must be signed, and since this website doesn't ask
110108
for 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

120118
Once 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
130129
each domain, this step shows you the file you need to host and the url you need
131130
to host it at.
132131

133132
After the file is being hosted, you need to tell Let's Encrypt to check the
134133
verify the challenge for that domain. That request must also be signed so
135134
there's one more signature that must be performed. The reason why this wasn't
136135
included 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
141140
server's command line (NOTE: this needs sudo permissions!). The file-base option
142141
just 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

145145
When you confirm that you're hosting the files, an ajax request is made to the
146146
challenge 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
153153
step prints the certificate and also prints the intermediate certificate you
154154
need 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
172172
clear what it's doing.
173173

174174
TODO (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

Comments
 (0)