rfc8555.go raw
1 // Copyright 2019 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4
5 package acme
6
7 import (
8 "context"
9 "crypto"
10 "encoding/base64"
11 "encoding/json"
12 "encoding/pem"
13 "errors"
14 "fmt"
15 "io"
16 "net/http"
17 "time"
18 )
19
20 // DeactivateReg permanently disables an existing account associated with c.Key.
21 // A deactivated account can no longer request certificate issuance or access
22 // resources related to the account, such as orders or authorizations.
23 //
24 // It only works with CAs implementing RFC 8555.
25 func (c *Client) DeactivateReg(ctx context.Context) error {
26 if _, err := c.Discover(ctx); err != nil { // required by c.accountKID
27 return err
28 }
29 url := string(c.accountKID(ctx))
30 if url == "" {
31 return ErrNoAccount
32 }
33 req := json.RawMessage(`{"status": "deactivated"}`)
34 res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
35 if err != nil {
36 return err
37 }
38 res.Body.Close()
39 return nil
40 }
41
42 // registerRFC is equivalent to c.Register but for CAs implementing RFC 8555.
43 // It expects c.Discover to have already been called.
44 func (c *Client) registerRFC(ctx context.Context, acct *Account, prompt func(tosURL string) bool) (*Account, error) {
45 c.cacheMu.Lock() // guard c.kid access
46 defer c.cacheMu.Unlock()
47
48 req := struct {
49 TermsAgreed bool `json:"termsOfServiceAgreed,omitempty"`
50 Contact []string `json:"contact,omitempty"`
51 ExternalAccountBinding *jsonWebSignature `json:"externalAccountBinding,omitempty"`
52 }{
53 Contact: acct.Contact,
54 }
55 if c.dir.Terms != "" {
56 req.TermsAgreed = prompt(c.dir.Terms)
57 }
58
59 // set 'externalAccountBinding' field if requested
60 if acct.ExternalAccountBinding != nil {
61 eabJWS, err := c.encodeExternalAccountBinding(acct.ExternalAccountBinding)
62 if err != nil {
63 return nil, fmt.Errorf("acme: failed to encode external account binding: %v", err)
64 }
65 req.ExternalAccountBinding = eabJWS
66 }
67
68 res, err := c.post(ctx, c.Key, c.dir.RegURL, req, wantStatus(
69 http.StatusOK, // account with this key already registered
70 http.StatusCreated, // new account created
71 ))
72 if err != nil {
73 return nil, err
74 }
75
76 defer res.Body.Close()
77 a, err := responseAccount(res)
78 if err != nil {
79 return nil, err
80 }
81 // Cache Account URL even if we return an error to the caller.
82 // It is by all means a valid and usable "kid" value for future requests.
83 c.KID = KeyID(a.URI)
84 if res.StatusCode == http.StatusOK {
85 return nil, ErrAccountAlreadyExists
86 }
87 return a, nil
88 }
89
90 // encodeExternalAccountBinding will encode an external account binding stanza
91 // as described in https://tools.ietf.org/html/rfc8555#section-7.3.4.
92 func (c *Client) encodeExternalAccountBinding(eab *ExternalAccountBinding) (*jsonWebSignature, error) {
93 jwk, err := jwkEncode(c.Key.Public())
94 if err != nil {
95 return nil, err
96 }
97 return jwsWithMAC(eab.Key, eab.KID, c.dir.RegURL, []byte(jwk))
98 }
99
100 // updateRegRFC is equivalent to c.UpdateReg but for CAs implementing RFC 8555.
101 // It expects c.Discover to have already been called.
102 func (c *Client) updateRegRFC(ctx context.Context, a *Account) (*Account, error) {
103 url := string(c.accountKID(ctx))
104 if url == "" {
105 return nil, ErrNoAccount
106 }
107 req := struct {
108 Contact []string `json:"contact,omitempty"`
109 }{
110 Contact: a.Contact,
111 }
112 res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
113 if err != nil {
114 return nil, err
115 }
116 defer res.Body.Close()
117 return responseAccount(res)
118 }
119
120 // getRegRFC is equivalent to c.GetReg but for CAs implementing RFC 8555.
121 // It expects c.Discover to have already been called.
122 func (c *Client) getRegRFC(ctx context.Context) (*Account, error) {
123 req := json.RawMessage(`{"onlyReturnExisting": true}`)
124 res, err := c.post(ctx, c.Key, c.dir.RegURL, req, wantStatus(http.StatusOK))
125 if e, ok := err.(*Error); ok && e.ProblemType == "urn:ietf:params:acme:error:accountDoesNotExist" {
126 return nil, ErrNoAccount
127 }
128 if err != nil {
129 return nil, err
130 }
131
132 defer res.Body.Close()
133 return responseAccount(res)
134 }
135
136 func responseAccount(res *http.Response) (*Account, error) {
137 var v struct {
138 Status string
139 Contact []string
140 Orders string
141 }
142 if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
143 return nil, fmt.Errorf("acme: invalid account response: %v", err)
144 }
145 return &Account{
146 URI: res.Header.Get("Location"),
147 Status: v.Status,
148 Contact: v.Contact,
149 OrdersURL: v.Orders,
150 }, nil
151 }
152
153 // accountKeyRollover attempts to perform account key rollover.
154 // On success it will change client.Key to the new key.
155 func (c *Client) accountKeyRollover(ctx context.Context, newKey crypto.Signer) error {
156 dir, err := c.Discover(ctx) // Also required by c.accountKID
157 if err != nil {
158 return err
159 }
160 kid := c.accountKID(ctx)
161 if kid == noKeyID {
162 return ErrNoAccount
163 }
164 oldKey, err := jwkEncode(c.Key.Public())
165 if err != nil {
166 return err
167 }
168 payload := struct {
169 Account string `json:"account"`
170 OldKey json.RawMessage `json:"oldKey"`
171 }{
172 Account: string(kid),
173 OldKey: json.RawMessage(oldKey),
174 }
175 inner, err := jwsEncodeJSON(payload, newKey, noKeyID, noNonce, dir.KeyChangeURL)
176 if err != nil {
177 return err
178 }
179
180 res, err := c.post(ctx, nil, dir.KeyChangeURL, base64.RawURLEncoding.EncodeToString(inner), wantStatus(http.StatusOK))
181 if err != nil {
182 return err
183 }
184 defer res.Body.Close()
185 c.Key = newKey
186 return nil
187 }
188
189 // AuthorizeOrder initiates the order-based application for certificate issuance,
190 // as opposed to pre-authorization in Authorize.
191 // It is only supported by CAs implementing RFC 8555.
192 //
193 // The caller then needs to fetch each authorization with GetAuthorization,
194 // identify those with StatusPending status and fulfill a challenge using Accept.
195 // Once all authorizations are satisfied, the caller will typically want to poll
196 // order status using WaitOrder until it's in StatusReady state.
197 // To finalize the order and obtain a certificate, the caller submits a CSR with CreateOrderCert.
198 func (c *Client) AuthorizeOrder(ctx context.Context, id []AuthzID, opt ...OrderOption) (*Order, error) {
199 dir, err := c.Discover(ctx)
200 if err != nil {
201 return nil, err
202 }
203
204 req := struct {
205 Identifiers []wireAuthzID `json:"identifiers"`
206 NotBefore string `json:"notBefore,omitempty"`
207 NotAfter string `json:"notAfter,omitempty"`
208 }{}
209 for _, v := range id {
210 req.Identifiers = append(req.Identifiers, wireAuthzID{
211 Type: v.Type,
212 Value: v.Value,
213 })
214 }
215 for _, o := range opt {
216 switch o := o.(type) {
217 case orderNotBeforeOpt:
218 req.NotBefore = time.Time(o).Format(time.RFC3339)
219 case orderNotAfterOpt:
220 req.NotAfter = time.Time(o).Format(time.RFC3339)
221 default:
222 // Package's fault if we let this happen.
223 panic(fmt.Sprintf("unsupported order option type %T", o))
224 }
225 }
226
227 res, err := c.post(ctx, nil, dir.OrderURL, req, wantStatus(http.StatusCreated))
228 if err != nil {
229 return nil, err
230 }
231 defer res.Body.Close()
232 return responseOrder(res)
233 }
234
235 // GetOrder retrieves an order identified by the given URL.
236 // For orders created with AuthorizeOrder, the url value is Order.URI.
237 //
238 // If a caller needs to poll an order until its status is final,
239 // see the WaitOrder method.
240 func (c *Client) GetOrder(ctx context.Context, url string) (*Order, error) {
241 if _, err := c.Discover(ctx); err != nil {
242 return nil, err
243 }
244
245 res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK))
246 if err != nil {
247 return nil, err
248 }
249 defer res.Body.Close()
250 return responseOrder(res)
251 }
252
253 // WaitOrder polls an order from the given URL until it is in one of the final states,
254 // StatusReady, StatusValid or StatusInvalid, the CA responded with a non-retryable error
255 // or the context is done.
256 //
257 // It returns a non-nil Order only if its Status is StatusReady or StatusValid.
258 // In all other cases WaitOrder returns an error.
259 // If the Status is StatusInvalid, the returned error is of type *OrderError.
260 func (c *Client) WaitOrder(ctx context.Context, url string) (*Order, error) {
261 if _, err := c.Discover(ctx); err != nil {
262 return nil, err
263 }
264 for {
265 res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK))
266 if err != nil {
267 return nil, err
268 }
269 o, err := responseOrder(res)
270 res.Body.Close()
271 switch {
272 case err != nil:
273 // Skip and retry.
274 case o.Status == StatusInvalid:
275 return nil, &OrderError{OrderURL: o.URI, Status: o.Status, Problem: o.Error}
276 case o.Status == StatusReady || o.Status == StatusValid:
277 return o, nil
278 }
279
280 d := retryAfter(res.Header.Get("Retry-After"))
281 if d == 0 {
282 // Default retry-after.
283 // Same reasoning as in WaitAuthorization.
284 d = time.Second
285 }
286 t := time.NewTimer(d)
287 select {
288 case <-ctx.Done():
289 t.Stop()
290 return nil, ctx.Err()
291 case <-t.C:
292 // Retry.
293 }
294 }
295 }
296
297 func responseOrder(res *http.Response) (*Order, error) {
298 var v struct {
299 Status string
300 Expires time.Time
301 Identifiers []wireAuthzID
302 NotBefore time.Time
303 NotAfter time.Time
304 Error *wireError
305 Authorizations []string
306 Finalize string
307 Certificate string
308 }
309 if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
310 return nil, fmt.Errorf("acme: error reading order: %v", err)
311 }
312 o := &Order{
313 URI: res.Header.Get("Location"),
314 Status: v.Status,
315 Expires: v.Expires,
316 NotBefore: v.NotBefore,
317 NotAfter: v.NotAfter,
318 AuthzURLs: v.Authorizations,
319 FinalizeURL: v.Finalize,
320 CertURL: v.Certificate,
321 }
322 for _, id := range v.Identifiers {
323 o.Identifiers = append(o.Identifiers, AuthzID{Type: id.Type, Value: id.Value})
324 }
325 if v.Error != nil {
326 o.Error = v.Error.error(nil /* headers */)
327 }
328 return o, nil
329 }
330
331 // CreateOrderCert submits the CSR (Certificate Signing Request) to a CA at the specified URL.
332 // The URL is the FinalizeURL field of an Order created with AuthorizeOrder.
333 //
334 // If the bundle argument is true, the returned value also contain the CA (issuer)
335 // certificate chain. Otherwise, only a leaf certificate is returned.
336 // The returned URL can be used to re-fetch the certificate using FetchCert.
337 //
338 // This method is only supported by CAs implementing RFC 8555. See CreateCert for pre-RFC CAs.
339 //
340 // CreateOrderCert returns an error if the CA's response is unreasonably large.
341 // Callers are encouraged to parse the returned value to ensure the certificate is valid and has the expected features.
342 func (c *Client) CreateOrderCert(ctx context.Context, url string, csr []byte, bundle bool) (der [][]byte, certURL string, err error) {
343 if _, err := c.Discover(ctx); err != nil { // required by c.accountKID
344 return nil, "", err
345 }
346
347 // RFC describes this as "finalize order" request.
348 req := struct {
349 CSR string `json:"csr"`
350 }{
351 CSR: base64.RawURLEncoding.EncodeToString(csr),
352 }
353 res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
354 if err != nil {
355 return nil, "", err
356 }
357 defer res.Body.Close()
358 o, err := responseOrder(res)
359 if err != nil {
360 return nil, "", err
361 }
362
363 // Wait for CA to issue the cert if they haven't.
364 if o.Status != StatusValid {
365 o, err = c.WaitOrder(ctx, o.URI)
366 }
367 if err != nil {
368 return nil, "", err
369 }
370 // The only acceptable status post finalize and WaitOrder is "valid".
371 if o.Status != StatusValid {
372 return nil, "", &OrderError{OrderURL: o.URI, Status: o.Status, Problem: o.Error}
373 }
374 crt, err := c.fetchCertRFC(ctx, o.CertURL, bundle)
375 return crt, o.CertURL, err
376 }
377
378 // fetchCertRFC downloads issued certificate from the given URL.
379 // It expects the CA to respond with PEM-encoded certificate chain.
380 //
381 // The URL argument is the CertURL field of Order.
382 func (c *Client) fetchCertRFC(ctx context.Context, url string, bundle bool) ([][]byte, error) {
383 res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK))
384 if err != nil {
385 return nil, err
386 }
387 defer res.Body.Close()
388
389 // Get all the bytes up to a sane maximum.
390 // Account very roughly for base64 overhead.
391 const max = maxCertChainSize + maxCertChainSize/33
392 b, err := io.ReadAll(io.LimitReader(res.Body, max+1))
393 if err != nil {
394 return nil, fmt.Errorf("acme: fetch cert response stream: %v", err)
395 }
396 if len(b) > max {
397 return nil, errors.New("acme: certificate chain is too big")
398 }
399
400 // Decode PEM chain.
401 var chain [][]byte
402 for {
403 var p *pem.Block
404 p, b = pem.Decode(b)
405 if p == nil {
406 break
407 }
408 if p.Type != "CERTIFICATE" {
409 return nil, fmt.Errorf("acme: invalid PEM cert type %q", p.Type)
410 }
411
412 chain = append(chain, p.Bytes)
413 if !bundle {
414 return chain, nil
415 }
416 if len(chain) > maxChainLen {
417 return nil, errors.New("acme: certificate chain is too long")
418 }
419 }
420 if len(chain) == 0 {
421 return nil, errors.New("acme: certificate chain is empty")
422 }
423 return chain, nil
424 }
425
426 // sends a cert revocation request in either JWK form when key is non-nil or KID form otherwise.
427 func (c *Client) revokeCertRFC(ctx context.Context, key crypto.Signer, cert []byte, reason CRLReasonCode) error {
428 req := &struct {
429 Cert string `json:"certificate"`
430 Reason int `json:"reason"`
431 }{
432 Cert: base64.RawURLEncoding.EncodeToString(cert),
433 Reason: int(reason),
434 }
435 res, err := c.post(ctx, key, c.dir.RevokeURL, req, wantStatus(http.StatusOK))
436 if err != nil {
437 if isAlreadyRevoked(err) {
438 // Assume it is not an error to revoke an already revoked cert.
439 return nil
440 }
441 return err
442 }
443 defer res.Body.Close()
444 return nil
445 }
446
447 func isAlreadyRevoked(err error) bool {
448 e, ok := err.(*Error)
449 return ok && e.ProblemType == "urn:ietf:params:acme:error:alreadyRevoked"
450 }
451
452 // ListCertAlternates retrieves any alternate certificate chain URLs for the
453 // given certificate chain URL. These alternate URLs can be passed to FetchCert
454 // in order to retrieve the alternate certificate chains.
455 //
456 // If there are no alternate issuer certificate chains, a nil slice will be
457 // returned.
458 func (c *Client) ListCertAlternates(ctx context.Context, url string) ([]string, error) {
459 if _, err := c.Discover(ctx); err != nil { // required by c.accountKID
460 return nil, err
461 }
462
463 res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK))
464 if err != nil {
465 return nil, err
466 }
467 defer res.Body.Close()
468
469 // We don't need the body but we need to discard it so we don't end up
470 // preventing keep-alive
471 if _, err := io.Copy(io.Discard, res.Body); err != nil {
472 return nil, fmt.Errorf("acme: cert alternates response stream: %v", err)
473 }
474 alts := linkHeader(res.Header, "alternate")
475 return alts, nil
476 }
477