Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 1 | // Copyright 2015 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 | |
Alex Vaghin | 611beeb | 2016-08-03 22:16:54 +0200 | [diff] [blame] | 5 | // Package acme provides an implementation of the |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 6 | // Automatic Certificate Management Environment (ACME) spec, |
| 7 | // most famously used by Let's Encrypt. |
| 8 | // |
| 9 | // The initial implementation of this package was based on an early version |
| 10 | // of the spec. The current implementation supports only the modern |
| 11 | // RFC 8555 but some of the old API surface remains for compatibility. |
| 12 | // While code using the old API will still compile, it will return an error. |
| 13 | // Note the deprecation comments to update your code. |
| 14 | // |
| 15 | // See https://tools.ietf.org/html/rfc8555 for the spec. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 16 | // |
Alex Vaghin | d3c1194 | 2016-08-31 20:47:52 +0200 | [diff] [blame] | 17 | // Most common scenarios will want to use autocert subdirectory instead, |
| 18 | // which provides automatic access to certificates from Let's Encrypt |
| 19 | // and any other ACME-based CA. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 20 | package acme |
| 21 | |
| 22 | import ( |
Brad Fitzpatrick | 88915cc | 2017-04-02 13:18:05 -0700 | [diff] [blame] | 23 | "context" |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 24 | "crypto" |
Alex Vaghin | 7e016f1 | 2016-08-21 18:20:10 +0200 | [diff] [blame] | 25 | "crypto/ecdsa" |
| 26 | "crypto/elliptic" |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 27 | "crypto/rand" |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 28 | "crypto/sha256" |
| 29 | "crypto/tls" |
| 30 | "crypto/x509" |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 31 | "crypto/x509/pkix" |
| 32 | "encoding/asn1" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 33 | "encoding/base64" |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 34 | "encoding/hex" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 35 | "encoding/json" |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 36 | "encoding/pem" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 37 | "errors" |
| 38 | "fmt" |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 39 | "math/big" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 40 | "net/http" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 41 | "strings" |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 42 | "sync" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 43 | "time" |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 44 | ) |
| 45 | |
Alex Vaghin | c126467 | 2018-07-23 17:26:11 +0200 | [diff] [blame] | 46 | const ( |
| 47 | // LetsEncryptURL is the Directory endpoint of Let's Encrypt CA. |
Alex Vaghin | a950601 | 2019-10-11 13:06:28 +0200 | [diff] [blame] | 48 | LetsEncryptURL = "https://acme-v02.api.letsencrypt.org/directory" |
Alex Vaghin | c126467 | 2018-07-23 17:26:11 +0200 | [diff] [blame] | 49 | |
| 50 | // ALPNProto is the ALPN protocol name used by a CA server when validating |
| 51 | // tls-alpn-01 challenges. |
| 52 | // |
Filippo Valsorda | 56440b8 | 2018-08-02 18:11:18 -0400 | [diff] [blame] | 53 | // Package users must ensure their servers can negotiate the ACME ALPN in |
| 54 | // order for tls-alpn-01 challenge verifications to succeed. |
| 55 | // See the crypto/tls package's Config.NextProtos field. |
Alex Vaghin | c126467 | 2018-07-23 17:26:11 +0200 | [diff] [blame] | 56 | ALPNProto = "acme-tls/1" |
| 57 | ) |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 58 | |
Jason Baker | 6ca56c2 | 2020-02-10 19:01:28 +0000 | [diff] [blame] | 59 | // idPeACMEIdentifier is the OID for the ACME extension for the TLS-ALPN challenge. |
| 60 | // https://tools.ietf.org/html/draft-ietf-acme-tls-alpn-05#section-5.1 |
| 61 | var idPeACMEIdentifier = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 1, 31} |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 62 | |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 63 | const ( |
| 64 | maxChainLen = 5 // max depth and breadth of a certificate chain |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 65 | maxCertSize = 1 << 20 // max size of a certificate, in DER bytes |
| 66 | // Used for decoding certs from application/pem-certificate-chain response, |
| 67 | // the default when in RFC mode. |
| 68 | maxCertChainSize = maxCertSize * maxChainLen |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 69 | |
| 70 | // Max number of collected nonces kept in memory. |
| 71 | // Expect usual peak of 1 or 2. |
| 72 | maxNonces = 100 |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 73 | ) |
| 74 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 75 | // Client is an ACME client. |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 76 | // |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 77 | // The only required field is Key. An example of creating a client with a new key |
| 78 | // is as follows: |
| 79 | // |
Russ Cox | 7b82a4e | 2022-04-11 13:06:45 -0400 | [diff] [blame] | 80 | // key, err := rsa.GenerateKey(rand.Reader, 2048) |
| 81 | // if err != nil { |
| 82 | // log.Fatal(err) |
| 83 | // } |
| 84 | // client := &Client{Key: key} |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 85 | type Client struct { |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 86 | // Key is the account key used to register with a CA and sign requests. |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 87 | // Key.Public() must return a *rsa.PublicKey or *ecdsa.PublicKey. |
Alex Vaghin | bfa7d42 | 2018-10-26 11:44:37 -0700 | [diff] [blame] | 88 | // |
| 89 | // The following algorithms are supported: |
| 90 | // RS256, ES256, ES384 and ES512. |
Axel Wagner | 56aed06 | 2022-10-11 09:15:35 +0200 | [diff] [blame] | 91 | // See RFC 7518 for more details about the algorithms. |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 92 | Key crypto.Signer |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 93 | |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 94 | // HTTPClient optionally specifies an HTTP client to use |
| 95 | // instead of http.DefaultClient. |
| 96 | HTTPClient *http.Client |
| 97 | |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 98 | // DirectoryURL points to the CA directory endpoint. |
| 99 | // If empty, LetsEncryptURL is used. |
| 100 | // Mutating this value after a successful call of Client's Discover method |
| 101 | // will have no effect. |
| 102 | DirectoryURL string |
| 103 | |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 104 | // RetryBackoff computes the duration after which the nth retry of a failed request |
| 105 | // should occur. The value of n for the first call on failure is 1. |
| 106 | // The values of r and resp are the request and response of the last failed attempt. |
| 107 | // If the returned value is negative or zero, no more retries are done and an error |
| 108 | // is returned to the caller of the original method. |
| 109 | // |
| 110 | // Requests which result in a 4xx client error are not retried, |
| 111 | // except for 400 Bad Request due to "bad nonce" errors and 429 Too Many Requests. |
| 112 | // |
| 113 | // If RetryBackoff is nil, a truncated exponential backoff algorithm |
| 114 | // with the ceiling of 10 seconds is used, where each subsequent retry n |
| 115 | // is done after either ("Retry-After" + jitter) or (2^n seconds + jitter), |
| 116 | // preferring the former if "Retry-After" header is found in the resp. |
| 117 | // The jitter is a random value up to 1 second. |
| 118 | RetryBackoff func(n int, r *http.Request, resp *http.Response) time.Duration |
| 119 | |
Filippo Valsorda | cc06ce4 | 2019-06-20 17:50:31 -0400 | [diff] [blame] | 120 | // UserAgent is prepended to the User-Agent header sent to the ACME server, |
| 121 | // which by default is this package's name and version. |
| 122 | // |
| 123 | // Reusable libraries and tools in particular should set this value to be |
| 124 | // identifiable by the server, in case they are causing issues. |
| 125 | UserAgent string |
| 126 | |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 127 | cacheMu sync.Mutex |
| 128 | dir *Directory // cached result of Client's Discover method |
Roland Shoemaker | 30dcbda | 2021-10-08 11:41:44 -0700 | [diff] [blame] | 129 | // KID is the key identifier provided by the CA. If not provided it will be |
| 130 | // retrieved from the CA by making a call to the registration endpoint. |
| 131 | KID KeyID |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 132 | |
| 133 | noncesMu sync.Mutex |
| 134 | nonces map[string]struct{} // nonces collected from previous responses |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 135 | } |
| 136 | |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 137 | // accountKID returns a key ID associated with c.Key, the account identity |
| 138 | // provided by the CA during RFC based registration. |
| 139 | // It assumes c.Discover has already been called. |
| 140 | // |
| 141 | // accountKID requires at most one network roundtrip. |
| 142 | // It caches only successful result. |
| 143 | // |
| 144 | // When in pre-RFC mode or when c.getRegRFC responds with an error, accountKID |
| 145 | // returns noKeyID. |
Roland Shoemaker | 30dcbda | 2021-10-08 11:41:44 -0700 | [diff] [blame] | 146 | func (c *Client) accountKID(ctx context.Context) KeyID { |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 147 | c.cacheMu.Lock() |
| 148 | defer c.cacheMu.Unlock() |
Roland Shoemaker | 30dcbda | 2021-10-08 11:41:44 -0700 | [diff] [blame] | 149 | if c.KID != noKeyID { |
| 150 | return c.KID |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 151 | } |
| 152 | a, err := c.getRegRFC(ctx) |
| 153 | if err != nil { |
| 154 | return noKeyID |
| 155 | } |
Roland Shoemaker | 30dcbda | 2021-10-08 11:41:44 -0700 | [diff] [blame] | 156 | c.KID = KeyID(a.URI) |
| 157 | return c.KID |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 158 | } |
| 159 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 160 | var errPreRFC = errors.New("acme: server does not support the RFC 8555 version of ACME") |
| 161 | |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 162 | // Discover performs ACME server discovery using c.DirectoryURL. |
| 163 | // |
| 164 | // It caches successful result. So, subsequent calls will not result in |
| 165 | // a network round-trip. This also means mutating c.DirectoryURL after successful call |
| 166 | // of this method will have no effect. |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 167 | func (c *Client) Discover(ctx context.Context) (Directory, error) { |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 168 | c.cacheMu.Lock() |
| 169 | defer c.cacheMu.Unlock() |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 170 | if c.dir != nil { |
| 171 | return *c.dir, nil |
| 172 | } |
| 173 | |
Alex Vaghin | a4c6cb3 | 2019-02-12 18:56:05 +0100 | [diff] [blame] | 174 | res, err := c.get(ctx, c.directoryURL(), wantStatus(http.StatusOK)) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 175 | if err != nil { |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 176 | return Directory{}, err |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 177 | } |
| 178 | defer res.Body.Close() |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 179 | c.addNonce(res.Header) |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 180 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 181 | var v struct { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 182 | Reg string `json:"newAccount"` |
| 183 | Authz string `json:"newAuthz"` |
| 184 | Order string `json:"newOrder"` |
| 185 | Revoke string `json:"revokeCert"` |
| 186 | Nonce string `json:"newNonce"` |
| 187 | KeyChange string `json:"keyChange"` |
| 188 | Meta struct { |
| 189 | Terms string `json:"termsOfService"` |
| 190 | Website string `json:"website"` |
| 191 | CAA []string `json:"caaIdentities"` |
| 192 | ExternalAcct bool `json:"externalAccountRequired"` |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 193 | } |
| 194 | } |
Alex Vaghin | c7af5bf | 2017-04-25 20:31:00 +0200 | [diff] [blame] | 195 | if err := json.NewDecoder(res.Body).Decode(&v); err != nil { |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 196 | return Directory{}, err |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 197 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 198 | if v.Order == "" { |
| 199 | return Directory{}, errPreRFC |
x1ddos | 2afe7c4 | 2019-08-20 17:44:11 +0200 | [diff] [blame] | 200 | } |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 201 | c.dir = &Directory{ |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 202 | RegURL: v.Reg, |
| 203 | AuthzURL: v.Authz, |
| 204 | OrderURL: v.Order, |
| 205 | RevokeURL: v.Revoke, |
| 206 | NonceURL: v.Nonce, |
| 207 | KeyChangeURL: v.KeyChange, |
| 208 | Terms: v.Meta.Terms, |
| 209 | Website: v.Meta.Website, |
| 210 | CAA: v.Meta.CAA, |
| 211 | ExternalAccountRequired: v.Meta.ExternalAcct, |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 212 | } |
| 213 | return *c.dir, nil |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 214 | } |
| 215 | |
Alex Vaghin | a4c6cb3 | 2019-02-12 18:56:05 +0100 | [diff] [blame] | 216 | func (c *Client) directoryURL() string { |
| 217 | if c.DirectoryURL != "" { |
| 218 | return c.DirectoryURL |
| 219 | } |
| 220 | return LetsEncryptURL |
| 221 | } |
| 222 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 223 | // CreateCert was part of the old version of ACME. It is incompatible with RFC 8555. |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 224 | // |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 225 | // Deprecated: this was for the pre-RFC 8555 version of ACME. Callers should use CreateOrderCert. |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 226 | func (c *Client) CreateCert(ctx context.Context, csr []byte, exp time.Duration, bundle bool) (der [][]byte, certURL string, err error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 227 | return nil, "", errPreRFC |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 228 | } |
| 229 | |
| 230 | // FetchCert retrieves already issued certificate from the given url, in DER format. |
| 231 | // It retries the request until the certificate is successfully retrieved, |
| 232 | // context is cancelled by the caller or an error response is received. |
| 233 | // |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 234 | // If the bundle argument is true, the returned value also contains the CA (issuer) |
| 235 | // certificate chain. |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 236 | // |
| 237 | // FetchCert returns an error if the CA's response or chain was unreasonably large. |
| 238 | // Callers are encouraged to parse the returned value to ensure the certificate is valid |
| 239 | // and has expected features. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 240 | func (c *Client) FetchCert(ctx context.Context, url string, bundle bool) ([][]byte, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 241 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 242 | return nil, err |
| 243 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 244 | return c.fetchCertRFC(ctx, url, bundle) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 245 | } |
| 246 | |
Alex Vaghin | 9fbab14 | 2016-08-16 16:28:56 +0200 | [diff] [blame] | 247 | // RevokeCert revokes a previously issued certificate cert, provided in DER format. |
| 248 | // |
| 249 | // The key argument, used to sign the request, must be authorized |
| 250 | // to revoke the certificate. It's up to the CA to decide which keys are authorized. |
| 251 | // For instance, the key pair of the certificate may be authorized. |
| 252 | // If the key is nil, c.Key is used instead. |
| 253 | func (c *Client) RevokeCert(ctx context.Context, key crypto.Signer, cert []byte, reason CRLReasonCode) error { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 254 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | 9fbab14 | 2016-08-16 16:28:56 +0200 | [diff] [blame] | 255 | return err |
| 256 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 257 | return c.revokeCertRFC(ctx, key, cert, reason) |
Alex Vaghin | 9fbab14 | 2016-08-16 16:28:56 +0200 | [diff] [blame] | 258 | } |
| 259 | |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 260 | // AcceptTOS always returns true to indicate the acceptance of a CA's Terms of Service |
Alex Vaghin | 1da79bd | 2016-06-10 12:38:58 +0100 | [diff] [blame] | 261 | // during account registration. See Register method of Client for more details. |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 262 | func AcceptTOS(tosURL string) bool { return true } |
Alex Vaghin | 1da79bd | 2016-06-10 12:38:58 +0100 | [diff] [blame] | 263 | |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 264 | // Register creates a new account with the CA using c.Key. |
| 265 | // It returns the registered account. The account acct is not modified. |
Alex Vaghin | 1da79bd | 2016-06-10 12:38:58 +0100 | [diff] [blame] | 266 | // |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 267 | // The registration may require the caller to agree to the CA's Terms of Service (TOS). |
Alex Vaghin | 1da79bd | 2016-06-10 12:38:58 +0100 | [diff] [blame] | 268 | // If so, and the account has not indicated the acceptance of the terms (see Account for details), |
| 269 | // Register calls prompt with a TOS URL provided by the CA. Prompt should report |
| 270 | // whether the caller agrees to the terms. To always accept the terms, the caller can use AcceptTOS. |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 271 | // |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 272 | // When interfacing with an RFC-compliant CA, non-RFC 8555 fields of acct are ignored |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 273 | // and prompt is called if Directory's Terms field is non-zero. |
| 274 | // Also see Error's Instance field for when a CA requires already registered accounts to agree |
| 275 | // to an updated Terms of Service. |
| 276 | func (c *Client) Register(ctx context.Context, acct *Account, prompt func(tosURL string) bool) (*Account, error) { |
James Kasten | 9d13527 | 2020-11-11 15:47:14 -0800 | [diff] [blame] | 277 | if c.Key == nil { |
| 278 | return nil, errors.New("acme: client.Key must be set to Register") |
| 279 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 280 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 281 | return nil, err |
| 282 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 283 | return c.registerRFC(ctx, acct, prompt) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 284 | } |
| 285 | |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 286 | // GetReg retrieves an existing account associated with c.Key. |
| 287 | // |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 288 | // The url argument is a legacy artifact of the pre-RFC 8555 API |
| 289 | // and is ignored. |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 290 | func (c *Client) GetReg(ctx context.Context, url string) (*Account, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 291 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 292 | return nil, err |
| 293 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 294 | return c.getRegRFC(ctx) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 295 | } |
| 296 | |
| 297 | // UpdateReg updates an existing registration. |
| 298 | // It returns an updated account copy. The provided account is not modified. |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 299 | // |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 300 | // The account's URI is ignored and the account URL associated with |
| 301 | // c.Key is used instead. |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 302 | func (c *Client) UpdateReg(ctx context.Context, acct *Account) (*Account, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 303 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 304 | return nil, err |
| 305 | } |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 306 | return c.updateRegRFC(ctx, acct) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 307 | } |
| 308 | |
Jason Baker | 403b017 | 2022-05-13 17:19:05 +0000 | [diff] [blame] | 309 | // AccountKeyRollover attempts to transition a client's account key to a new key. |
| 310 | // On success client's Key is updated which is not concurrency safe. |
| 311 | // On failure an error will be returned. |
| 312 | // The new key is already registered with the ACME provider if the following is true: |
Russ Cox | bc19a97 | 2022-08-16 10:48:38 -0400 | [diff] [blame] | 313 | // - error is of type acme.Error |
| 314 | // - StatusCode should be 409 (Conflict) |
| 315 | // - Location header will have the KID of the associated account |
Jason Baker | 403b017 | 2022-05-13 17:19:05 +0000 | [diff] [blame] | 316 | // |
| 317 | // More about account key rollover can be found at |
| 318 | // https://tools.ietf.org/html/rfc8555#section-7.3.5. |
| 319 | func (c *Client) AccountKeyRollover(ctx context.Context, newKey crypto.Signer) error { |
| 320 | return c.accountKeyRollover(ctx, newKey) |
| 321 | } |
| 322 | |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 323 | // Authorize performs the initial step in the pre-authorization flow, |
| 324 | // as opposed to order-based flow. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 325 | // The caller will then need to choose from and perform a set of returned |
| 326 | // challenges using c.Accept in order to successfully complete authorization. |
Alex Vaghin | 1ba5ec0 | 2016-08-19 14:32:09 +0200 | [diff] [blame] | 327 | // |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 328 | // Once complete, the caller can use AuthorizeOrder which the CA |
| 329 | // should provision with the already satisfied authorization. |
| 330 | // For pre-RFC CAs, the caller can proceed directly to requesting a certificate |
| 331 | // using CreateCert method. |
| 332 | // |
Alex Vaghin | 1ba5ec0 | 2016-08-19 14:32:09 +0200 | [diff] [blame] | 333 | // If an authorization has been previously granted, the CA may return |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 334 | // a valid authorization which has its Status field set to StatusValid. |
| 335 | // |
| 336 | // More about pre-authorization can be found at |
| 337 | // https://tools.ietf.org/html/rfc8555#section-7.4.1. |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 338 | func (c *Client) Authorize(ctx context.Context, domain string) (*Authorization, error) { |
Alex Vaghin | b01c7a7 | 2019-01-29 19:10:45 +0100 | [diff] [blame] | 339 | return c.authorize(ctx, "dns", domain) |
| 340 | } |
| 341 | |
| 342 | // AuthorizeIP is the same as Authorize but requests IP address authorization. |
| 343 | // Clients which successfully obtain such authorization may request to issue |
| 344 | // a certificate for IP addresses. |
| 345 | // |
| 346 | // See the ACME spec extension for more details about IP address identifiers: |
| 347 | // https://tools.ietf.org/html/draft-ietf-acme-ip. |
| 348 | func (c *Client) AuthorizeIP(ctx context.Context, ipaddr string) (*Authorization, error) { |
| 349 | return c.authorize(ctx, "ip", ipaddr) |
| 350 | } |
| 351 | |
| 352 | func (c *Client) authorize(ctx context.Context, typ, val string) (*Authorization, error) { |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 353 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | c2f4947 | 2016-06-10 12:13:04 +0100 | [diff] [blame] | 354 | return nil, err |
| 355 | } |
| 356 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 357 | type authzID struct { |
| 358 | Type string `json:"type"` |
| 359 | Value string `json:"value"` |
| 360 | } |
| 361 | req := struct { |
| 362 | Resource string `json:"resource"` |
| 363 | Identifier authzID `json:"identifier"` |
| 364 | }{ |
| 365 | Resource: "new-authz", |
Alex Vaghin | b01c7a7 | 2019-01-29 19:10:45 +0100 | [diff] [blame] | 366 | Identifier: authzID{Type: typ, Value: val}, |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 367 | } |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 368 | res, err := c.post(ctx, nil, c.dir.AuthzURL, req, wantStatus(http.StatusCreated)) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 369 | if err != nil { |
| 370 | return nil, err |
| 371 | } |
| 372 | defer res.Body.Close() |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 373 | |
| 374 | var v wireAuthz |
| 375 | if err := json.NewDecoder(res.Body).Decode(&v); err != nil { |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 376 | return nil, fmt.Errorf("acme: invalid response: %v", err) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 377 | } |
Alex Vaghin | 1ba5ec0 | 2016-08-19 14:32:09 +0200 | [diff] [blame] | 378 | if v.Status != StatusPending && v.Status != StatusValid { |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 379 | return nil, fmt.Errorf("acme: unexpected status: %s", v.Status) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 380 | } |
| 381 | return v.authorization(res.Header.Get("Location")), nil |
| 382 | } |
| 383 | |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 384 | // GetAuthorization retrieves an authorization identified by the given URL. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 385 | // |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 386 | // If a caller needs to poll an authorization until its status is final, |
| 387 | // see the WaitAuthorization method. |
| 388 | func (c *Client) GetAuthorization(ctx context.Context, url string) (*Authorization, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 389 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 390 | return nil, err |
| 391 | } |
| 392 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 393 | res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK)) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 394 | if err != nil { |
| 395 | return nil, err |
| 396 | } |
| 397 | defer res.Body.Close() |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 398 | var v wireAuthz |
| 399 | if err := json.NewDecoder(res.Body).Decode(&v); err != nil { |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 400 | return nil, fmt.Errorf("acme: invalid response: %v", err) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 401 | } |
| 402 | return v.authorization(url), nil |
| 403 | } |
| 404 | |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 405 | // RevokeAuthorization relinquishes an existing authorization identified |
| 406 | // by the given URL. |
| 407 | // The url argument is an Authorization.URI value. |
| 408 | // |
| 409 | // If successful, the caller will be required to obtain a new authorization |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 410 | // using the Authorize or AuthorizeOrder methods before being able to request |
| 411 | // a new certificate for the domain associated with the authorization. |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 412 | // |
| 413 | // It does not revoke existing certificates. |
| 414 | func (c *Client) RevokeAuthorization(ctx context.Context, url string) error { |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 415 | if _, err := c.Discover(ctx); err != nil { |
| 416 | return err |
| 417 | } |
| 418 | |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 419 | req := struct { |
| 420 | Resource string `json:"resource"` |
Alex Vaghin | ca7e7f1 | 2016-10-25 14:52:55 +0200 | [diff] [blame] | 421 | Status string `json:"status"` |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 422 | Delete bool `json:"delete"` |
| 423 | }{ |
| 424 | Resource: "authz", |
Alex Vaghin | ca7e7f1 | 2016-10-25 14:52:55 +0200 | [diff] [blame] | 425 | Status: "deactivated", |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 426 | Delete: true, |
| 427 | } |
Alex Vaghin | a832865 | 2019-08-28 23:16:55 +0200 | [diff] [blame] | 428 | res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK)) |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 429 | if err != nil { |
| 430 | return err |
| 431 | } |
| 432 | defer res.Body.Close() |
Alex Vaghin | f944096 | 2016-09-07 16:50:43 +0200 | [diff] [blame] | 433 | return nil |
| 434 | } |
| 435 | |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 436 | // WaitAuthorization polls an authorization at the given URL |
| 437 | // until it is in one of the final states, StatusValid or StatusInvalid, |
Alex Vaghin | 91a49db | 2018-02-28 16:18:34 +0100 | [diff] [blame] | 438 | // the ACME CA responded with a 4xx error code, or the context is done. |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 439 | // |
| 440 | // It returns a non-nil Authorization only if its Status is StatusValid. |
| 441 | // In all other cases WaitAuthorization returns an error. |
Alex Vaghin | 141c762 | 2017-04-12 13:08:46 +0200 | [diff] [blame] | 442 | // If the Status is StatusInvalid, the returned error is of type *AuthorizationError. |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 443 | func (c *Client) WaitAuthorization(ctx context.Context, url string) (*Authorization, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 444 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 445 | return nil, err |
| 446 | } |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 447 | for { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 448 | res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK, http.StatusAccepted)) |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 449 | if err != nil { |
| 450 | return nil, err |
| 451 | } |
Alex Vaghin | 91a49db | 2018-02-28 16:18:34 +0100 | [diff] [blame] | 452 | |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 453 | var raw wireAuthz |
| 454 | err = json.NewDecoder(res.Body).Decode(&raw) |
| 455 | res.Body.Close() |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 456 | switch { |
| 457 | case err != nil: |
| 458 | // Skip and retry. |
| 459 | case raw.Status == StatusValid: |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 460 | return raw.authorization(url), nil |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 461 | case raw.Status == StatusInvalid: |
Alex Vaghin | 141c762 | 2017-04-12 13:08:46 +0200 | [diff] [blame] | 462 | return nil, raw.error(url) |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 463 | } |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 464 | |
| 465 | // Exponential backoff is implemented in c.get above. |
| 466 | // This is just to prevent continuously hitting the CA |
| 467 | // while waiting for a final authorization status. |
| 468 | d := retryAfter(res.Header.Get("Retry-After")) |
| 469 | if d == 0 { |
| 470 | // Given that the fastest challenges TLS-SNI and HTTP-01 |
| 471 | // require a CA to make at least 1 network round trip |
| 472 | // and most likely persist a challenge state, |
| 473 | // this default delay seems reasonable. |
| 474 | d = time.Second |
| 475 | } |
| 476 | t := time.NewTimer(d) |
| 477 | select { |
| 478 | case <-ctx.Done(): |
| 479 | t.Stop() |
| 480 | return nil, ctx.Err() |
| 481 | case <-t.C: |
| 482 | // Retry. |
Alex Vaghin | b35ccbc | 2016-08-19 11:32:22 +0200 | [diff] [blame] | 483 | } |
| 484 | } |
| 485 | } |
| 486 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 487 | // GetChallenge retrieves the current status of an challenge. |
| 488 | // |
| 489 | // A client typically polls a challenge status using this method. |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 490 | func (c *Client) GetChallenge(ctx context.Context, url string) (*Challenge, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 491 | if _, err := c.Discover(ctx); err != nil { |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 492 | return nil, err |
| 493 | } |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 494 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 495 | res, err := c.postAsGet(ctx, url, wantStatus(http.StatusOK, http.StatusAccepted)) |
Alex Vaghin | 4663e18 | 2019-09-09 15:54:00 -0400 | [diff] [blame] | 496 | if err != nil { |
| 497 | return nil, err |
| 498 | } |
| 499 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 500 | defer res.Body.Close() |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 501 | v := wireChallenge{URI: url} |
| 502 | if err := json.NewDecoder(res.Body).Decode(&v); err != nil { |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 503 | return nil, fmt.Errorf("acme: invalid response: %v", err) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 504 | } |
| 505 | return v.challenge(), nil |
| 506 | } |
| 507 | |
| 508 | // Accept informs the server that the client accepts one of its challenges |
| 509 | // previously obtained with c.Authorize. |
| 510 | // |
| 511 | // The server will then perform the validation asynchronously. |
Alex Vaghin | 807ffea | 2016-08-16 15:36:38 +0200 | [diff] [blame] | 512 | func (c *Client) Accept(ctx context.Context, chal *Challenge) (*Challenge, error) { |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 513 | if _, err := c.Discover(ctx); err != nil { |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 514 | return nil, err |
| 515 | } |
| 516 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 517 | res, err := c.post(ctx, nil, chal.URI, json.RawMessage("{}"), wantStatus( |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 518 | http.StatusOK, // according to the spec |
| 519 | http.StatusAccepted, // Let's Encrypt: see https://goo.gl/WsJ7VT (acme-divergences.md) |
| 520 | )) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 521 | if err != nil { |
| 522 | return nil, err |
| 523 | } |
| 524 | defer res.Body.Close() |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 525 | |
| 526 | var v wireChallenge |
| 527 | if err := json.NewDecoder(res.Body).Decode(&v); err != nil { |
Alex Vaghin | a548aac | 2016-08-13 22:38:22 +0200 | [diff] [blame] | 528 | return nil, fmt.Errorf("acme: invalid response: %v", err) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 529 | } |
| 530 | return v.challenge(), nil |
| 531 | } |
| 532 | |
Alex Vaghin | 351dc6a | 2016-08-24 15:50:57 +0200 | [diff] [blame] | 533 | // DNS01ChallengeRecord returns a DNS record value for a dns-01 challenge response. |
| 534 | // A TXT record containing the returned value must be provisioned under |
| 535 | // "_acme-challenge" name of the domain being validated. |
| 536 | // |
| 537 | // The token argument is a Challenge.Token value. |
| 538 | func (c *Client) DNS01ChallengeRecord(token string) (string, error) { |
| 539 | ka, err := keyAuth(c.Key.Public(), token) |
| 540 | if err != nil { |
| 541 | return "", err |
| 542 | } |
| 543 | b := sha256.Sum256([]byte(ka)) |
| 544 | return base64.RawURLEncoding.EncodeToString(b[:]), nil |
| 545 | } |
| 546 | |
Alex Vaghin | 1f83de1 | 2016-08-14 22:48:00 +0200 | [diff] [blame] | 547 | // HTTP01ChallengeResponse returns the response for an http-01 challenge. |
| 548 | // Servers should respond with the value to HTTP requests at the URL path |
| 549 | // provided by HTTP01ChallengePath to validate the challenge and prove control |
| 550 | // over a domain name. |
| 551 | // |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 552 | // The token argument is a Challenge.Token value. |
Alex Vaghin | 1f83de1 | 2016-08-14 22:48:00 +0200 | [diff] [blame] | 553 | func (c *Client) HTTP01ChallengeResponse(token string) (string, error) { |
| 554 | return keyAuth(c.Key.Public(), token) |
| 555 | } |
| 556 | |
| 557 | // HTTP01ChallengePath returns the URL path at which the response for an http-01 challenge |
| 558 | // should be provided by the servers. |
| 559 | // The response value can be obtained with HTTP01ChallengeResponse. |
| 560 | // |
| 561 | // The token argument is a Challenge.Token value. |
| 562 | func (c *Client) HTTP01ChallengePath(token string) string { |
| 563 | return "/.well-known/acme-challenge/" + token |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 564 | } |
| 565 | |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 566 | // TLSSNI01ChallengeCert creates a certificate for TLS-SNI-01 challenge response. |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 567 | // |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 568 | // Deprecated: This challenge type is unused in both draft-02 and RFC versions of the ACME spec. |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 569 | func (c *Client) TLSSNI01ChallengeCert(token string, opt ...CertOption) (cert tls.Certificate, name string, err error) { |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 570 | ka, err := keyAuth(c.Key.Public(), token) |
| 571 | if err != nil { |
Alex Vaghin | 595bbbd | 2016-08-11 17:03:39 +0200 | [diff] [blame] | 572 | return tls.Certificate{}, "", err |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 573 | } |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 574 | b := sha256.Sum256([]byte(ka)) |
| 575 | h := hex.EncodeToString(b[:]) |
Alex Vaghin | 595bbbd | 2016-08-11 17:03:39 +0200 | [diff] [blame] | 576 | name = fmt.Sprintf("%s.%s.acme.invalid", h[:32], h[32:]) |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 577 | cert, err = tlsChallengeCert([]string{name}, opt) |
Alex Vaghin | 595bbbd | 2016-08-11 17:03:39 +0200 | [diff] [blame] | 578 | if err != nil { |
| 579 | return tls.Certificate{}, "", err |
| 580 | } |
| 581 | return cert, name, nil |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 582 | } |
| 583 | |
| 584 | // TLSSNI02ChallengeCert creates a certificate for TLS-SNI-02 challenge response. |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 585 | // |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 586 | // Deprecated: This challenge type is unused in both draft-02 and RFC versions of the ACME spec. |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 587 | func (c *Client) TLSSNI02ChallengeCert(token string, opt ...CertOption) (cert tls.Certificate, name string, err error) { |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 588 | b := sha256.Sum256([]byte(token)) |
| 589 | h := hex.EncodeToString(b[:]) |
| 590 | sanA := fmt.Sprintf("%s.%s.token.acme.invalid", h[:32], h[32:]) |
| 591 | |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 592 | ka, err := keyAuth(c.Key.Public(), token) |
| 593 | if err != nil { |
Alex Vaghin | 595bbbd | 2016-08-11 17:03:39 +0200 | [diff] [blame] | 594 | return tls.Certificate{}, "", err |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 595 | } |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 596 | b = sha256.Sum256([]byte(ka)) |
| 597 | h = hex.EncodeToString(b[:]) |
| 598 | sanB := fmt.Sprintf("%s.%s.ka.acme.invalid", h[:32], h[32:]) |
| 599 | |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 600 | cert, err = tlsChallengeCert([]string{sanA, sanB}, opt) |
Alex Vaghin | 595bbbd | 2016-08-11 17:03:39 +0200 | [diff] [blame] | 601 | if err != nil { |
| 602 | return tls.Certificate{}, "", err |
| 603 | } |
| 604 | return cert, sanA, nil |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 605 | } |
| 606 | |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 607 | // TLSALPN01ChallengeCert creates a certificate for TLS-ALPN-01 challenge response. |
| 608 | // Servers can present the certificate to validate the challenge and prove control |
| 609 | // over a domain name. For more details on TLS-ALPN-01 see |
| 610 | // https://tools.ietf.org/html/draft-shoemaker-acme-tls-alpn-00#section-3 |
| 611 | // |
| 612 | // The token argument is a Challenge.Token value. |
| 613 | // If a WithKey option is provided, its private part signs the returned cert, |
| 614 | // and the public part is used to specify the signee. |
| 615 | // If no WithKey option is provided, a new ECDSA key is generated using P-256 curve. |
| 616 | // |
| 617 | // The returned certificate is valid for the next 24 hours and must be presented only when |
| 618 | // the server name in the TLS ClientHello matches the domain, and the special acme-tls/1 ALPN protocol |
| 619 | // has been specified. |
| 620 | func (c *Client) TLSALPN01ChallengeCert(token, domain string, opt ...CertOption) (cert tls.Certificate, err error) { |
| 621 | ka, err := keyAuth(c.Key.Public(), token) |
| 622 | if err != nil { |
| 623 | return tls.Certificate{}, err |
| 624 | } |
| 625 | shasum := sha256.Sum256([]byte(ka)) |
Roland Shoemaker | e6b1200 | 2018-06-13 13:00:12 -0700 | [diff] [blame] | 626 | extValue, err := asn1.Marshal(shasum[:]) |
| 627 | if err != nil { |
| 628 | return tls.Certificate{}, err |
| 629 | } |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 630 | acmeExtension := pkix.Extension{ |
Jason Baker | 6ca56c2 | 2020-02-10 19:01:28 +0000 | [diff] [blame] | 631 | Id: idPeACMEIdentifier, |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 632 | Critical: true, |
Roland Shoemaker | e6b1200 | 2018-06-13 13:00:12 -0700 | [diff] [blame] | 633 | Value: extValue, |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 634 | } |
| 635 | |
| 636 | tmpl := defaultTLSChallengeCertTemplate() |
| 637 | |
| 638 | var newOpt []CertOption |
| 639 | for _, o := range opt { |
| 640 | switch o := o.(type) { |
| 641 | case *certOptTemplate: |
| 642 | t := *(*x509.Certificate)(o) // shallow copy is ok |
| 643 | tmpl = &t |
| 644 | default: |
| 645 | newOpt = append(newOpt, o) |
| 646 | } |
| 647 | } |
| 648 | tmpl.ExtraExtensions = append(tmpl.ExtraExtensions, acmeExtension) |
| 649 | newOpt = append(newOpt, WithTemplate(tmpl)) |
| 650 | return tlsChallengeCert([]string{domain}, newOpt) |
| 651 | } |
| 652 | |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 653 | // popNonce returns a nonce value previously stored with c.addNonce |
Alex Vaghin | 2682ddc | 2019-08-21 01:03:43 +0200 | [diff] [blame] | 654 | // or fetches a fresh one from c.dir.NonceURL. |
| 655 | // If NonceURL is empty, it first tries c.directoryURL() and, failing that, |
| 656 | // the provided url. |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 657 | func (c *Client) popNonce(ctx context.Context, url string) (string, error) { |
| 658 | c.noncesMu.Lock() |
| 659 | defer c.noncesMu.Unlock() |
| 660 | if len(c.nonces) == 0 { |
Alex Vaghin | 2682ddc | 2019-08-21 01:03:43 +0200 | [diff] [blame] | 661 | if c.dir != nil && c.dir.NonceURL != "" { |
| 662 | return c.fetchNonce(ctx, c.dir.NonceURL) |
| 663 | } |
Alex Vaghin | a4c6cb3 | 2019-02-12 18:56:05 +0100 | [diff] [blame] | 664 | dirURL := c.directoryURL() |
| 665 | v, err := c.fetchNonce(ctx, dirURL) |
| 666 | if err != nil && url != dirURL { |
| 667 | v, err = c.fetchNonce(ctx, url) |
| 668 | } |
| 669 | return v, err |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 670 | } |
| 671 | var nonce string |
| 672 | for nonce = range c.nonces { |
| 673 | delete(c.nonces, nonce) |
| 674 | break |
| 675 | } |
| 676 | return nonce, nil |
| 677 | } |
| 678 | |
James Hartig | cbc3d08 | 2017-04-09 14:29:52 -0400 | [diff] [blame] | 679 | // clearNonces clears any stored nonces |
| 680 | func (c *Client) clearNonces() { |
| 681 | c.noncesMu.Lock() |
| 682 | defer c.noncesMu.Unlock() |
| 683 | c.nonces = make(map[string]struct{}) |
| 684 | } |
| 685 | |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 686 | // addNonce stores a nonce value found in h (if any) for future use. |
| 687 | func (c *Client) addNonce(h http.Header) { |
| 688 | v := nonceFromHeader(h) |
| 689 | if v == "" { |
| 690 | return |
| 691 | } |
| 692 | c.noncesMu.Lock() |
| 693 | defer c.noncesMu.Unlock() |
| 694 | if len(c.nonces) >= maxNonces { |
| 695 | return |
| 696 | } |
| 697 | if c.nonces == nil { |
| 698 | c.nonces = make(map[string]struct{}) |
| 699 | } |
| 700 | c.nonces[v] = struct{}{} |
| 701 | } |
| 702 | |
Brad Fitzpatrick | 6022e33 | 2017-04-08 17:54:05 +0000 | [diff] [blame] | 703 | func (c *Client) fetchNonce(ctx context.Context, url string) (string, error) { |
Alex Vaghin | df8d471 | 2018-04-26 21:26:21 +0200 | [diff] [blame] | 704 | r, err := http.NewRequest("HEAD", url, nil) |
| 705 | if err != nil { |
| 706 | return "", err |
| 707 | } |
| 708 | resp, err := c.doNoRetry(ctx, r) |
Alex Vaghin | 9278377 | 2017-02-08 14:36:45 +0100 | [diff] [blame] | 709 | if err != nil { |
| 710 | return "", err |
| 711 | } |
| 712 | defer resp.Body.Close() |
| 713 | nonce := nonceFromHeader(resp.Header) |
| 714 | if nonce == "" { |
| 715 | if resp.StatusCode > 299 { |
| 716 | return "", responseError(resp) |
| 717 | } |
| 718 | return "", errors.New("acme: nonce not found") |
| 719 | } |
| 720 | return nonce, nil |
| 721 | } |
| 722 | |
| 723 | func nonceFromHeader(h http.Header) string { |
| 724 | return h.Get("Replay-Nonce") |
| 725 | } |
| 726 | |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 727 | // linkHeader returns URI-Reference values of all Link headers |
| 728 | // with relation-type rel. |
| 729 | // See https://tools.ietf.org/html/rfc5988#section-5 for details. |
| 730 | func linkHeader(h http.Header, rel string) []string { |
| 731 | var links []string |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 732 | for _, v := range h["Link"] { |
| 733 | parts := strings.Split(v, ";") |
| 734 | for _, p := range parts { |
| 735 | p = strings.TrimSpace(p) |
| 736 | if !strings.HasPrefix(p, "rel=") { |
| 737 | continue |
| 738 | } |
| 739 | if v := strings.Trim(p[4:], `"`); v == rel { |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 740 | links = append(links, strings.Trim(parts[0], "<>")) |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 741 | } |
| 742 | } |
| 743 | } |
Alex Vaghin | 6575f7e | 2016-08-10 16:19:56 +0200 | [diff] [blame] | 744 | return links |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 745 | } |
| 746 | |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 747 | // keyAuth generates a key authorization string for a given token. |
Anmol Sethi | e0d166c | 2016-08-04 00:47:19 -0400 | [diff] [blame] | 748 | func keyAuth(pub crypto.PublicKey, token string) (string, error) { |
| 749 | th, err := JWKThumbprint(pub) |
| 750 | if err != nil { |
| 751 | return "", err |
| 752 | } |
| 753 | return fmt.Sprintf("%s.%s", token, th), nil |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 754 | } |
| 755 | |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 756 | // defaultTLSChallengeCertTemplate is a template used to create challenge certs for TLS challenges. |
| 757 | func defaultTLSChallengeCertTemplate() *x509.Certificate { |
| 758 | return &x509.Certificate{ |
| 759 | SerialNumber: big.NewInt(1), |
| 760 | NotBefore: time.Now(), |
| 761 | NotAfter: time.Now().Add(24 * time.Hour), |
| 762 | BasicConstraintsValid: true, |
| 763 | KeyUsage: x509.KeyUsageKeyEncipherment | x509.KeyUsageDigitalSignature, |
| 764 | ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, |
| 765 | } |
| 766 | } |
| 767 | |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 768 | // tlsChallengeCert creates a temporary certificate for TLS-SNI challenges |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 769 | // with the given SANs and auto-generated public/private key pair. |
Alex Vaghin | 959b3af | 2017-10-16 15:58:10 +0200 | [diff] [blame] | 770 | // The Subject Common Name is set to the first SAN to aid debugging. |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 771 | // To create a cert with a custom key pair, specify WithKey option. |
| 772 | func tlsChallengeCert(san []string, opt []CertOption) (tls.Certificate, error) { |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 773 | var key crypto.Signer |
| 774 | tmpl := defaultTLSChallengeCertTemplate() |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 775 | for _, o := range opt { |
| 776 | switch o := o.(type) { |
| 777 | case *certOptKey: |
| 778 | if key != nil { |
| 779 | return tls.Certificate{}, errors.New("acme: duplicate key option") |
| 780 | } |
| 781 | key = o.key |
Alex Vaghin | e311231 | 2016-09-12 12:18:32 +0200 | [diff] [blame] | 782 | case *certOptTemplate: |
Maciej Dębski | 8ac0e0d | 2018-06-07 13:59:11 +0000 | [diff] [blame] | 783 | t := *(*x509.Certificate)(o) // shallow copy is ok |
Alex Vaghin | e311231 | 2016-09-12 12:18:32 +0200 | [diff] [blame] | 784 | tmpl = &t |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 785 | default: |
| 786 | // package's fault, if we let this happen: |
| 787 | panic(fmt.Sprintf("unsupported option type %T", o)) |
| 788 | } |
| 789 | } |
| 790 | if key == nil { |
| 791 | var err error |
| 792 | if key, err = ecdsa.GenerateKey(elliptic.P256(), rand.Reader); err != nil { |
| 793 | return tls.Certificate{}, err |
| 794 | } |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 795 | } |
Alex Vaghin | e311231 | 2016-09-12 12:18:32 +0200 | [diff] [blame] | 796 | tmpl.DNSNames = san |
Alex Vaghin | 959b3af | 2017-10-16 15:58:10 +0200 | [diff] [blame] | 797 | if len(san) > 0 { |
| 798 | tmpl.Subject.CommonName = san[0] |
| 799 | } |
Alex Vaghin | e311231 | 2016-09-12 12:18:32 +0200 | [diff] [blame] | 800 | |
| 801 | der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, key.Public(), key) |
Alex Vaghin | b13fc1f | 2016-08-25 09:06:35 +0200 | [diff] [blame] | 802 | if err != nil { |
| 803 | return tls.Certificate{}, err |
| 804 | } |
Alex Vaghin | 5f961cd | 2016-08-10 16:35:40 +0200 | [diff] [blame] | 805 | return tls.Certificate{ |
| 806 | Certificate: [][]byte{der}, |
| 807 | PrivateKey: key, |
| 808 | }, nil |
Alex Vaghin | 7a1054f | 2016-08-03 21:58:22 +0200 | [diff] [blame] | 809 | } |
| 810 | |
| 811 | // encodePEM returns b encoded as PEM with block of type typ. |
| 812 | func encodePEM(typ string, b []byte) []byte { |
| 813 | pb := &pem.Block{Type: typ, Bytes: b} |
| 814 | return pem.EncodeToMemory(pb) |
| 815 | } |
| 816 | |
Ben Burkert | 65fa2f7 | 2022-01-22 13:59:02 -0500 | [diff] [blame] | 817 | // timeNow is time.Now, except in tests which can mess with it. |
Alex Vaghin | 1777f3b | 2016-03-18 12:12:46 +0000 | [diff] [blame] | 818 | var timeNow = time.Now |