1# Boulder flow diagrams
2
3Boulder is built out of multiple components that can be deployed in different
4security contexts.
5
6In order for you to understand how Boulder works and ensure it's working correctly,
7this document lays out how various operations flow through boulder. It is
8expected you're already familiar with the [ACME
9protocol](https://github.com/ietf-wg-acme/acme). We show a diagram of how calls
10go between Boulder components, and provide notes on what each
11component does to help the process along. Each step is in its own subsection
12below, in roughly the order that they happen in certificate issuance for both
13ACME v1 and ACME v2.
14
15A couple of notes:
16
17* For simplicity, we do not show interactions with the Storage Authority.
18 The SA simply acts as a common data store for the various components. It
19 is written to by the RA (registrations and authorizations) and the CA
20 (certificates), and read by WFEv2, RA, and CA.
21
22* The interactions shown in the diagrams are the calls that go between
23 components. These calls are done via [gRPC](https://grpc.io/).
24
25* In various places the Boulder implementation of ACME diverges from the current
26 RFC draft. These divergences are documented in [docs/acme-divergences.md](https://github.com/letsencrypt/boulder/blob/main/docs/acme-divergences.md).
27
28* The RFC draft leaves many decisions on it's implementation to the discretion
29 of server and client developers. The ACME RFC is also silent on some matters,
30 as the relevant implementation details would be influenced by other RFCs.
31 Several of these details and decisions particular to Boulder are documented in [docs/acme-implementation_details.md](https://github.com/letsencrypt/boulder/blob/main/docs/acme-implementation_details.md).
32
33* We focus on the primary ACME operations and do not include all possible
34 interactions (e.g. account key change, authorization deactivation)
35
36* We presently ignore the POST-as-GET construction introduced in
37 [draft-15](https://tools.ietf.org/html/draft-ietf-acme-acme-15) and show
38 unauthenticated GET requests for ACME v2 operations.
39
40## New Account/Registration
41
42ACME v2:
43
44```
451: Client ---newAccount---> WFEv2
462: WFEv2 ---NewRegistration--> RA
473: WFEv2 <-------return------- RA
484: Client <---------------- WFEv2
49```
50
51Notes:
52
53* 1-2: WFEv2 does the following:
54 * Verify that the request is a POST
55 * Verify the JWS signature on the POST body
56 * Parse the registration/account object
57 * Filters illegal fields from the registration/account object
58 * We ignore the WFEv2 possibly returning early based on the OnlyReturnExisting
59 flag to simplify explanation.
60
61* 2-3: RA does the following:
62 * Verify that the registered account key is acceptable
63 * Create a new registration/account and add the client's information
64 * Store the registration/account (which gives it an ID)
65 * Return the registration/account as stored
66
67* 3-4: WFEv2 does the following:
68 * Return the registration/account, with a unique URL
69
70
71## Updated Registration
72
73ACME v2:
74
75```
761: Client ---acct--> WFEv2
772: WFEv2 ---UpdateRegistration--> RA
783: WFEv2 <--------return--------- RA
794: Client <--------- WFEv2
80```
81
82* 1-2: WFEv2 does the following:
83 * Verify that the request is a POST
84 * Verify the JWS signature on the POST body
85 * Verify that the JWS signature is by a registered key
86 * Verify that the JWS key matches the registration for the URL
87 * WFEv2: Verify that the account agrees to the terms of service
88 * Parse the registration/account object
89 * Filter illegal fields from the registration/account object
90
91* 2-3: RA does the following:
92 * Merge the update into the existing registration/account
93 * Store the updated registration/account
94 * Return the updated registration/account
95
96* 3-4: WFEv2 does the following:
97 * Return the updated registration/account
98
99## New Authorization (ACME v1 Only)
100
101ACME v2:
102We do not implement "pre-authorization" and the newAuthz endpoint for ACME v2.
103Clients are expected to get authorizations by way of creating orders.
104
105* 1-2: WFEv2 does the following:
106 * Verify that the request is a POST
107 * Verify the JWS signature on the POST body
108 * Verify that the JWS signature is by a registered key
109 * Verify that the client has indicated agreement to terms
110 * Parse the initial authorization object
111
112* 2-3: RA does the following:
113 * Verify that the requested identifier is allowed by policy
114 * Verify that the CAA policy for for each DNS identifier allows issuance
115 * Create challenges as required by policy
116 * Construct URIs for the challenges
117 * Store the authorization
118
119* 3-4: WFEv2 does the following:
120 * Return the authorization, with a unique URL
121
122## New Order (ACME v2 Only)
123
124ACME v2:
125```
1261: Client ---newOrder---> WFEv2
1272: WFEv2 -------NewOrder------> RA
1283: WFEv2 <-------return-------- RA
1294: Client <-------------- WFEv2
130```
131
132* 1-2: WFEv2 does the following:
133 * Verify that the request is a POST
134 * Verify the JWS signature on the POST body
135 * Verify that the JWS signature is by a registered key
136 * Parse the initial order object and identifiers
137
138* 2-3: RA does the following:
139 * Verify that the requested identifiers are allowed by policy
140 * Create authorizations and challenges as required by policy
141 * Construct URIs for the challenges and authorizations
142 * Store the authorizations and challenges
143
144* 3-4: WFEv2 does the following:
145 * Return the order object, containing authorizations and challenges, with
146 a unique URL
147
148## Challenge Response
149
150ACME v2:
151
152```
1531: Client ---chal--> WFEv2
1542: WFEv2 ---UpdateAuthorization--> RA
1553: RA ---PerformValidation--> VA
1564: Client <~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~> VA
1575: RA <-------return--------- VA
1586: WFEv2 <--------return---------- RA
1597: Client <--------- WFEv2
160```
161
162* 1-2: WFEv2 does the following:
163 * Look up the referenced authorization object
164 * Look up the referenced challenge within the authorization object
165 * Verify that the request is a POST
166 * Verify the JWS signature on the POST body
167 * Verify that the JWS signature is by a registered key
168 * Verify that the JWS key corresponds to the authorization
169
170* 2-3: RA does the following:
171 * Store the updated authorization object
172
173* 3-4: VA does the following:
174 * Dispatch a goroutine to do validation
175
176* 4-5: RA does the following:
177 * Return the updated authorization object
178
179* 5-6: WFEv2 does the following:
180 * Return the updated authorization object
181
182* 6: VA does the following:
183 * Validate domain control according to the challenge responded to
184 * Notify the RA of the result
185
186* 6-7: RA does the following:
187 * Check that a sufficient set of challenges has been validated
188 * Mark the authorization as valid or invalid
189 * Store the updated authorization object
190
191* 6-7: WFEv2 does the following:
192 * Return the updated challenge object
193
194## Authorization Poll
195
196ACME v2:
197
198```
1991: Client ---authz--> WFEv2
2002: Client <---------- WFEv2
201```
202
203* 1-2: WFEv2 does the following:
204 * Look up the referenced authorization
205 * Verify that the request is a GET
206 * Return the authorization object
207
208## Order Poll (ACME v2 Only)
209
210ACME v1:
211This version of the protocol does not use order objects.
212
213ACME v2:
214
215```
2161: Client ---order--> WFEv2
2172: Client <---------- WFEv2
218```
219
220* 1-2: WFEv2 does the following:
221 * Look up the referenced order
222 * Return the order object
223
224## New Certificate (ACME v1 Only)
225
226ACME v2:
227This version of the protocol expects certificate issuance to occur only through
228order finalization and does not offer the new-cert endpoint.
229
230* 1-2: WFEv2 does the following:
231 * Verify that the request is a POST
232 * Verify the JWS signature on the POST body
233 * Verify that the JWS signature is by a registered key
234 * Verify that the client has indicated agreement to terms
235 * Parse the certificate request object
236
237* 3-4: RA does the following:
238 * Verify the PKCS#10 CSR in the certificate request object
239 * Verify that the CSR has a non-zero number of domain names
240 * Verify that the public key in the CSR is different from the account key
241 * For each authorization referenced in the certificate request
242 * Retrieve the authorization from the database
243 * Verify that the authorization corresponds to the account key
244 * Verify that the authorization is valid
245 * Verify that the CAA policy for the identifier is still valid
246 * Verify that all domains in the CSR are covered by authorizations
247 * Compute the earliest expiration date among the authorizations
248 * Instruct the CA to issue a precertificate
249
250* 3-4: CA does the following:
251 * Verify that the public key in the CSR meets quality requirements
252 * RSA only for the moment
253 * Modulus >= 2048 bits and not divisible by small primes
254 * Exponent > 2^16
255 * Remove any duplicate names in the CSR
256 * Verify that all names are allowed by policy (also checked at new-authz time)
257 * Verify that the issued cert will not be valid longer than the CA cert
258 * Verify that the issued cert will not be valid longer than the underlying authorizations
259 * Open a CA DB transaction and allocate a new serial number
260 * Sign a poisoned precertificate
261
262* 5-6: RA does the following:
263 * Collect the SCTs needed to satisfy the ctpolicy
264 * Instruct the CA to issue a final certificate with the SCTs
265
266* 5-6: CA does the following:
267 * Remove the precertificate poison and sign a final certificate with SCTs provided by the RA
268 * Create the first OCSP response for the final certificate
269 * Sign the final certificate and the first OCSP response
270 * Store the final certificate
271 * Commit the CA DB transaction if everything worked
272 * Return the final certificate serial number
273
274* 6-7: RA does the following:
275 * Log the success or failure of the request
276 * Return the certificate object
277
278* 7-8: WFEv2 does the following:
279 * Create a URL from the certificate's serial number
280 * Return the certificate with its URL
281
282## Order Finalization (ACME v2 Only)
283
284ACME v2:
285
286```
2871: Client ---order finalize--> WFEv2
2882: WFEv2 ----FinalizeOrder--> RA
2893: RA ----------IssuePreCertificate---------> CA
2904: RA <---------------return----------------- CA
2915: RA ---IssueCertificateForPrecertificate--> CA
2926: RA <---------------return----------------- CA
2937: WFEv2 <----return--------- RA
2948: Client <------------- WFEv2
295```
296
297* 1-2: WFEv2 does the following:
298 * Verify that the request is a POST
299 * Verify the JWS signature on the POST body
300 * Verify that the JWS signature is by a registered key
301 * Verify the registered account owns the order being finalized
302 * Parse the certificate signing request (CSR) from the request
303
304* 2-4: RA does the following:
305 * Verify the PKCS#10 CSR in the certificate request object
306 * Verify that the CSR has a non-zero number of domain names
307 * Verify that the public key in the CSR is different from the account key
308 * Retrieve and verify the status and expiry of the order object
309 * For each identifier referenced in the order request
310 * Retrieve the authorization from the database
311 * Verify that the authorization corresponds to the account key
312 * Verify that the authorization is valid
313 * Verify that the CAA policy for the identifier is still valid
314 * Verify that all domains in the order are included in the CSR
315 * Instruct the CA to issue a precertificate
316
317* 3-4: CA does the following:
318 * Verify that the public key in the CSR meets quality requirements
319 * RSA only for the moment
320 * Modulus >= 2048 bits and not divisible by small primes
321 * Exponent > 2^16
322 * Remove any duplicate names in the CSR
323 * Verify that all names are allowed by policy (also checked at new-authz time)
324 * Verify that the issued cert will not be valid longer than the CA cert
325 * Verify that the issued cert will not be valid longer than the underlying authorizations
326 * Open a CA DB transaction and allocate a new serial number
327 * Sign a poisoned precertificate
328
329* 5-6: RA does the following
330 * Collect the SCTs needed to satisfy the ctpolicy
331 * Instruct the CA to issue a final certificate with the SCTs
332
333* 5-6: CA does the following:
334 * Sign a final certificate with SCTs provided by the RA
335 * Create the first OCSP response for the final certificate
336 * Sign the final certificate and the first OCSP response
337 * Store the final certificate
338 * Commit the CA DB transaction if everything worked
339 * Return the final certificate serial number
340
341* 6-7: RA does the following:
342 * Log the success or failure of the request
343 * Updates the order to have status valid if the request succeeded
344 * Updates the order with the serial number of the certificate object
345
346* 7-8: WFEv2 does the following:
347 * Create a URL from the order's certificate's serial number
348 * Return the order with a certificate URL
349
350## Revoke Certificate
351
352ACME v2:
353
354```
3551: Client ---cert--> WFEv2
3562: WFEv2 ---RevokeCertByApplicant--> RA
3573: WFEv2 <-----------return--------- RA
3584: Client <--------- WFEv2
359```
360or
361```
3621: Client ---cert--> WFEv2
3632: WFEv2 ------RevokeCertByKey-----> RA
3643: WFEv2 <-----------return--------- RA
3654: Client <--------- WFEv2
366```
367
368
369* 1-2:WFEv2 does the following:
370 * Verify that the request is a POST
371 * Verify the JWS signature on the POST body
372 * Verify that the JWS signature is either:
373 * The account key for the certificate, or
374 * The account key for an account with valid authorizations for all names in
375 the certificate, or
376 * The public key from the certificate
377 * Parse the certificate request object
378
379* 3-4: RA does the following:
380 * Mark the certificate as revoked.
381 * Log the success or failure of the revocation
382
383* Later, (not-pictured) the CA will:
384 * Sign an OCSP response indicating revoked status for this certificate
385 * Store the OCSP response in the database
386
387* 3-4: WFEv2 does the following:
388 * Return an indication of the success or failure of the revocation
View as plain text