github.com/letsencrypt/boulder@v0.20251208.0/docs/DESIGN.md (about) 1 # Boulder flow diagrams 2 3 Boulder is built out of multiple components that can be deployed in different 4 security contexts. 5 6 In order for you to understand how Boulder works and ensure it's working correctly, 7 this document lays out how various operations flow through boulder. It is 8 expected you're already familiar with the [ACME 9 protocol](https://github.com/ietf-wg-acme/acme). We show a diagram of how calls 10 go between Boulder components, and provide notes on what each 11 component does to help the process along. Each step is in its own subsection 12 below, in roughly the order that they happen in certificate issuance for both 13 ACME v1 and ACME v2. 14 15 A 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 42 ACME v2: 43 44 ``` 45 1: Client ---newAccount---> WFEv2 46 2: WFEv2 ---NewRegistration--> RA 47 3: WFEv2 <-------return------- RA 48 4: Client <---------------- WFEv2 49 ``` 50 51 Notes: 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 73 ACME v2: 74 75 ``` 76 1: Client ---acct--> WFEv2 77 2: WFEv2 ---UpdateRegistration--> RA 78 3: WFEv2 <--------return--------- RA 79 4: 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 101 ACME v2: 102 We do not implement "pre-authorization" and the newAuthz endpoint for ACME v2. 103 Clients 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 124 ACME v2: 125 ``` 126 1: Client ---newOrder---> WFEv2 127 2: WFEv2 -------NewOrder------> RA 128 3: WFEv2 <-------return-------- RA 129 4: 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 150 ACME v2: 151 152 ``` 153 1: Client ---chal--> WFEv2 154 2: WFEv2 ---UpdateAuthorization--> RA 155 3: RA ---PerformValidation--> VA 156 4: Client <~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~> VA 157 5: RA <-------return--------- VA 158 6: WFEv2 <--------return---------- RA 159 7: 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 196 ACME v2: 197 198 ``` 199 1: Client ---authz--> WFEv2 200 2: 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 210 ACME v1: 211 This version of the protocol does not use order objects. 212 213 ACME v2: 214 215 ``` 216 1: Client ---order--> WFEv2 217 2: 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 226 ACME v2: 227 This version of the protocol expects certificate issuance to occur only through 228 order 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 identifiers 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 284 ACME v2: 285 286 ``` 287 1: Client ---order finalize--> WFEv2 288 2: WFEv2 ----FinalizeOrder--> RA 289 3: RA ----------IssuePreCertificate---------> CA 290 4: RA <---------------return----------------- CA 291 5: RA ---IssueCertificateForPrecertificate--> CA 292 6: RA <---------------return----------------- CA 293 7: WFEv2 <----return--------- RA 294 8: 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 identifiers 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 352 ACME v2: 353 354 ``` 355 1: Client ---cert--> WFEv2 356 2: WFEv2 ---RevokeCertByApplicant--> RA 357 3: WFEv2 <-----------return--------- RA 358 4: Client <--------- WFEv2 359 ``` 360 or 361 ``` 362 1: Client ---cert--> WFEv2 363 2: WFEv2 ------RevokeCertByKey-----> RA 364 3: WFEv2 <-----------return--------- RA 365 4: 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