func AcceptTOS(tosURLstring)bool

func JWKThumbprint(pubcrypto.PublicKey) (string,error)

func RateLimit(errerror) (time.Duration,bool)

type Account struct {// URI is the account unique ID, which is also a URL used to retrieve// account data from the CA.// When interfacing withRFC 8555-compliant CAs, URI is the "kid" field// value in JWS signed requests.URIstring// Contact is a slice of contact info used during registration.// Seehttps://tools.ietf.org/html/rfc8555#section-7.3 for supported// formats.Contact []string// Status indicates current account status as returned by the CA.// Possible values are StatusValid, StatusDeactivated, and StatusRevoked.Statusstring// OrdersURL is a URL from which a list of orders submitted by this account// can be fetched.OrdersURLstring// The terms user has agreed to.// A value not matching CurrentTerms indicates that the user hasn't agreed// to the actual Terms of Service of the CA.//// It is non-RFC 8555 compliant. Package users can store the ToS they agree to// during Client's Register call in the prompt callback function.AgreedTermsstring// Actual terms of a CA.//// It is non-RFC 8555 compliant. Use Directory's Terms field.// When a CA updates their terms and requires an account agreement,// a URL at which instructions to do so is available in Error's Instance field.CurrentTermsstring// Authz is the authorization URL used to initiate a new authz flow.//// It is non-RFC 8555 compliant. Use Directory's AuthzURL or OrderURL.Authzstring// Authorizations is a URI from which a list of authorizations// granted to this account can be fetched via a GET request.//// It is non-RFC 8555 compliant and is obsoleted by OrdersURL.Authorizationsstring// Certificates is a URI from which a list of certificates// issued for this account can be fetched via a GET request.//// It is non-RFC 8555 compliant and is obsoleted by OrdersURL.Certificatesstring// ExternalAccountBinding represents an arbitrary binding to an account of// the CA which the ACME server is tied to.// Seehttps://tools.ietf.org/html/rfc8555#section-7.3.4 for more details.ExternalAccountBinding *ExternalAccountBinding}

type Authorization struct {// URI uniquely identifies a authorization.URIstring// Status is the current status of an authorization.// Possible values are StatusPending, StatusValid, StatusInvalid, StatusDeactivated,// StatusExpired and StatusRevoked.Statusstring// Identifier is what the account is authorized to represent.IdentifierAuthzID// The timestamp after which the CA considers the authorization invalid.Expirestime.Time// Wildcard is true for authorizations of a wildcard domain name.Wildcardbool// Challenges that the client needs to fulfill in order to prove possession// of the identifier (for pending authorizations).// For valid authorizations, the challenge that was validated.// For invalid authorizations, the challenge that was attempted and failed.////RFC 8555 compatible CAs require users to fuflfill only one of the challenges.Challenges []*Challenge// A collection of sets of challenges, each of which would be sufficient// to prove possession of the identifier.// Clients must complete a set of challenges that covers at least one set.// Challenges are identified by their indices in the challenges array.// If this field is empty, the client needs to complete all challenges.//// This field is unused inRFC 8555.Combinations [][]int}

type AuthorizationError struct {// URI uniquely identifies the failed Authorization.URIstring// Identifier is an AuthzID.Value of the failed Authorization.Identifierstring// Errors is a collection of non-nil error values of Challenge items// of the failed Authorization.Errors []error}

func (*AuthorizationError)Error¶

func (a *AuthorizationError) Error()string

type AuthzID struct {Typestring// The type of identifier, "dns" or "ip".Valuestring// The identifier itself, e.g. "example.org".}

funcDomainIDs¶

func DomainIDs(names ...string) []AuthzID

DomainIDs creates a slice of AuthzID with "dns" identifier type.

funcIPIDs¶

func IPIDs(addr ...string) []AuthzID

IPIDs creates a slice of AuthzID with "ip" identifier type.Each element of addr is textual form of an address as definedinRFC 1123 Section 2.1 for IPv4 and inRFC 5952 Section 4 for IPv6.

type CRLReasonCodeint

const (CRLReasonUnspecifiedCRLReasonCode = 0CRLReasonKeyCompromiseCRLReasonCode = 1CRLReasonCACompromiseCRLReasonCode = 2CRLReasonAffiliationChangedCRLReasonCode = 3CRLReasonSupersededCRLReasonCode = 4CRLReasonCessationOfOperationCRLReasonCode = 5CRLReasonCertificateHoldCRLReasonCode = 6CRLReasonRemoveFromCRLCRLReasonCode = 8CRLReasonPrivilegeWithdrawnCRLReasonCode = 9CRLReasonAACompromiseCRLReasonCode = 10)

CRL reason codes as defined inRFC 5280.

type CertOption interface {// contains filtered or unexported methods}

funcWithKey¶

func WithKey(keycrypto.Signer)CertOption

WithKey creates an option holding a private/public key pair.The private part signs a certificate, and the public part represents the signee.

funcWithTemplate¶

func WithTemplate(t *x509.Certificate)CertOption

WithTemplate creates an option for specifying a certificate template.See x509.CreateCertificate for template usage details.

In TLS ChallengeCert methods, the template is also used as parent,resulting in a self-signed certificate.The DNSNames field of t is always overwritten for tls-sni challenge certs.

type Challenge struct {// Type is the challenge type, e.g. "http-01", "tls-alpn-01", "dns-01".Typestring// URI is where a challenge response can be posted to.URIstring// Token is a random value that uniquely identifies the challenge.Tokenstring// Status identifies the status of this challenge.// InRFC 8555, possible values are StatusPending, StatusProcessing, StatusValid,// and StatusInvalid.Statusstring// Validated is the time at which the CA validated this challenge.// Always zero value in pre-RFC 8555.Validatedtime.Time// Error indicates the reason for an authorization failure// when this challenge was used.// The type of a non-nil value is *Error.Errorerror// Payload is the JSON-formatted payload that the client sends// to the server to indicate it is ready to respond to the challenge.// When unset, it defaults to an empty JSON object: {}.// For most challenges, the client must not set Payload,// seehttps://tools.ietf.org/html/rfc8555#section-7.5.1.// Payload is used only for newer challenges (such as "device-attest-01")// where the client must send additional data for the server to validate// the challenge.Payloadjson.RawMessage}

type Client struct {// Key is the account key used to register with a CA and sign requests.// Key.Public() must return a *rsa.PublicKey or *ecdsa.PublicKey.//// The following algorithms are supported:// RS256, ES256, ES384 and ES512.// SeeRFC 7518 for more details about the algorithms.Keycrypto.Signer// HTTPClient optionally specifies an HTTP client to use// instead of http.DefaultClient.HTTPClient *http.Client// DirectoryURL points to the CA directory endpoint.// If empty, LetsEncryptURL is used.// Mutating this value after a successful call of Client's Discover method// will have no effect.DirectoryURLstring// RetryBackoff computes the duration after which the nth retry of a failed request// should occur. The value of n for the first call on failure is 1.// The values of r and resp are the request and response of the last failed attempt.// If the returned value is negative or zero, no more retries are done and an error// is returned to the caller of the original method.//// Requests which result in a 4xx client error are not retried,// except for 400 Bad Request due to "bad nonce" errors and 429 Too Many Requests.//// If RetryBackoff is nil, a truncated exponential backoff algorithm// with the ceiling of 10 seconds is used, where each subsequent retry n// is done after either ("Retry-After" + jitter) or (2^n seconds + jitter),// preferring the former if "Retry-After" header is found in the resp.// The jitter is a random value up to 1 second.RetryBackoff func(nint, r *http.Request, resp *http.Response)time.Duration// UserAgent is prepended to the User-Agent header sent to the ACME server,// which by default is this package's name and version.//// Reusable libraries and tools in particular should set this value to be// identifiable by the server, in case they are causing issues.UserAgentstring// KID is the key identifier provided by the CA. If not provided it will be// retrieved from the CA by making a call to the registration endpoint.KIDKeyID// contains filtered or unexported fields}

func (*Client)Accept¶

func (c *Client) Accept(ctxcontext.Context, chal *Challenge) (*Challenge,error)

Accept informs the server that the client accepts one of its challengespreviously obtained with c.Authorize.

The server will then perform the validation asynchronously.

func (*Client)AccountKeyRollover¶

func (c *Client) AccountKeyRollover(ctxcontext.Context, newKeycrypto.Signer)error

AccountKeyRollover attempts to transition a client's account key to a new key.On success client's Key is updated which is not concurrency safe.On failure an error will be returned.The new key is already registered with the ACME provider if the following is true:

• error is of type acme.Error
• StatusCode should be 409 (Conflict)
• Location header will have the KID of the associated account

More about account key rollover can be found athttps://tools.ietf.org/html/rfc8555#section-7.3.5.

func (*Client)Authorize¶

func (c *Client) Authorize(ctxcontext.Context, domainstring) (*Authorization,error)

Authorize performs the initial step in the pre-authorization flow,as opposed to order-based flow.The caller will then need to choose from and perform a set of returnedchallenges using c.Accept in order to successfully complete authorization.

Once complete, the caller can use AuthorizeOrder which the CAshould provision with the already satisfied authorization.For pre-RFC CAs, the caller can proceed directly to requesting a certificateusing CreateCert method.

If an authorization has been previously granted, the CA may returna valid authorization which has its Status field set to StatusValid.

More about pre-authorization can be found athttps://tools.ietf.org/html/rfc8555#section-7.4.1.

func (*Client)AuthorizeIP¶

func (c *Client) AuthorizeIP(ctxcontext.Context, ipaddrstring) (*Authorization,error)

AuthorizeIP is the same as Authorize but requests IP address authorization.Clients which successfully obtain such authorization may request to issuea certificate for IP addresses.

See the ACME spec extension for more details about IP address identifiers:https://tools.ietf.org/html/draft-ietf-acme-ip.

func (*Client)AuthorizeOrder¶

func (c *Client) AuthorizeOrder(ctxcontext.Context, id []AuthzID, opt ...OrderOption) (*Order,error)

AuthorizeOrder initiates the order-based application for certificate issuance,as opposed to pre-authorization in Authorize.It is only supported by CAs implementingRFC 8555.

The caller then needs to fetch each authorization with GetAuthorization,identify those with StatusPending status and fulfill a challenge using Accept.Once all authorizations are satisfied, the caller will typically want to pollorder status using WaitOrder until it's in StatusReady state.To finalize the order and obtain a certificate, the caller submits a CSR with CreateOrderCert.

func (*Client)CreateOrderCert¶

func (c *Client) CreateOrderCert(ctxcontext.Context, urlstring, csr []byte, bundlebool) (der [][]byte, certURLstring, errerror)

CreateOrderCert submits the CSR (Certificate Signing Request) to a CA at the specified URL.The URL is the FinalizeURL field of an Order created with AuthorizeOrder.

If the bundle argument is true, the returned value also contain the CA (issuer)certificate chain. Otherwise, only a leaf certificate is returned.The returned URL can be used to re-fetch the certificate using FetchCert.

This method is only supported by CAs implementingRFC 8555. See CreateCert for pre-RFC CAs.

CreateOrderCert returns an error if the CA's response is unreasonably large.Callers are encouraged to parse the returned value to ensure the certificate is valid and has the expected features.

func (*Client)DNS01ChallengeRecord¶

func (c *Client) DNS01ChallengeRecord(tokenstring) (string,error)

DNS01ChallengeRecord returns a DNS record value for a dns-01 challenge response.A TXT record containing the returned value must be provisioned under"_acme-challenge" name of the domain being validated.

The token argument is a Challenge.Token value.

func (*Client)DeactivateReg¶

func (c *Client) DeactivateReg(ctxcontext.Context)error

DeactivateReg permanently disables an existing account associated with c.Key.A deactivated account can no longer request certificate issuance or accessresources related to the account, such as orders or authorizations.

It only works with CAs implementingRFC 8555.

func (*Client)Discover¶

func (c *Client) Discover(ctxcontext.Context) (Directory,error)

Discover performs ACME server discovery using c.DirectoryURL.

It caches successful result. So, subsequent calls will not result ina network round-trip. This also means mutating c.DirectoryURL after successful callof this method will have no effect.

func (*Client)FetchCert¶

func (c *Client) FetchCert(ctxcontext.Context, urlstring, bundlebool) ([][]byte,error)

FetchCert retrieves already issued certificate from the given url, in DER format.It retries the request until the certificate is successfully retrieved,context is cancelled by the caller or an error response is received.

If the bundle argument is true, the returned value also contains the CA (issuer)certificate chain.

FetchCert returns an error if the CA's response or chain was unreasonably large.Callers are encouraged to parse the returned value to ensure the certificate is validand has expected features.

func (*Client)FetchRenewalInfo¶

func (c *Client) FetchRenewalInfo(ctxcontext.Context, leaf []byte) (*RenewalInfo,error)

FetchRenewalInfo retrieves the RenewalInfo from Directory.RenewalInfoURL.

func (*Client)GetAuthorization¶

func (c *Client) GetAuthorization(ctxcontext.Context, urlstring) (*Authorization,error)

GetAuthorization retrieves an authorization identified by the given URL.

If a caller needs to poll an authorization until its status is final,see the WaitAuthorization method.

func (*Client)GetChallenge¶

func (c *Client) GetChallenge(ctxcontext.Context, urlstring) (*Challenge,error)

GetChallenge retrieves the current status of an challenge.

A client typically polls a challenge status using this method.

func (*Client)GetOrder¶

func (c *Client) GetOrder(ctxcontext.Context, urlstring) (*Order,error)

GetOrder retrives an order identified by the given URL.For orders created with AuthorizeOrder, the url value is Order.URI.

If a caller needs to poll an order until its status is final,see the WaitOrder method.

func (*Client)GetReg¶

func (c *Client) GetReg(ctxcontext.Context, urlstring) (*Account,error)

GetReg retrieves an existing account associated with c.Key.

The url argument is a legacy artifact of the pre-RFC 8555 APIand is ignored.

func (*Client)HTTP01ChallengePath¶

func (c *Client) HTTP01ChallengePath(tokenstring)string

HTTP01ChallengePath returns the URL path at which the response for an http-01 challengeshould be provided by the servers.The response value can be obtained with HTTP01ChallengeResponse.

The token argument is a Challenge.Token value.

func (*Client)HTTP01ChallengeResponse¶

func (c *Client) HTTP01ChallengeResponse(tokenstring) (string,error)

HTTP01ChallengeResponse returns the response for an http-01 challenge.Servers should respond with the value to HTTP requests at the URL pathprovided by HTTP01ChallengePath to validate the challenge and prove controlover a domain name.

The token argument is a Challenge.Token value.

func (*Client)ListCertAlternates¶

func (c *Client) ListCertAlternates(ctxcontext.Context, urlstring) ([]string,error)

ListCertAlternates retrieves any alternate certificate chain URLs for thegiven certificate chain URL. These alternate URLs can be passed to FetchCertin order to retrieve the alternate certificate chains.

If there are no alternate issuer certificate chains, a nil slice will bereturned.

func (*Client)Register¶

func (c *Client) Register(ctxcontext.Context, acct *Account, prompt func(tosURLstring)bool) (*Account,error)

Register creates a new account with the CA using c.Key.It returns the registered account. The account acct is not modified.

The registration may require the caller to agree to the CA's Terms of Service (TOS).If so, and the account has not indicated the acceptance of the terms (see Account for details),Register calls prompt with a TOS URL provided by the CA. Prompt should reportwhether the caller agrees to the terms. To always accept the terms, the caller can use AcceptTOS.

When interfacing with an RFC-compliant CA, non-RFC 8555 fields of acct are ignoredand prompt is called if Directory's Terms field is non-zero.Also see Error's Instance field for when a CA requires already registered accounts to agreeto an updated Terms of Service.

func (*Client)RevokeAuthorization¶

func (c *Client) RevokeAuthorization(ctxcontext.Context, urlstring)error

RevokeAuthorization relinquishes an existing authorization identifiedby the given URL.The url argument is an Authorization.URI value.

If successful, the caller will be required to obtain a new authorizationusing the Authorize or AuthorizeOrder methods before being able to requesta new certificate for the domain associated with the authorization.

It does not revoke existing certificates.

func (*Client)RevokeCert¶

func (c *Client) RevokeCert(ctxcontext.Context, keycrypto.Signer, cert []byte, reasonCRLReasonCode)error

RevokeCert revokes a previously issued certificate cert, provided in DER format.

The key argument, used to sign the request, must be authorizedto revoke the certificate. It's up to the CA to decide which keys are authorized.For instance, the key pair of the certificate may be authorized.If the key is nil, c.Key is used instead.

func (*Client)TLSALPN01ChallengeCert¶

func (c *Client) TLSALPN01ChallengeCert(token, domainstring, opt ...CertOption) (certtls.Certificate, errerror)

TLSALPN01ChallengeCert creates a certificate for TLS-ALPN-01 challenge response.Servers can present the certificate to validate the challenge and prove controlover a domain name. For more details on TLS-ALPN-01 seehttps://tools.ietf.org/html/draft-shoemaker-acme-tls-alpn-00#section-3

The token argument is a Challenge.Token value.If a WithKey option is provided, its private part signs the returned cert,and the public part is used to specify the signee.If no WithKey option is provided, a new ECDSA key is generated using P-256 curve.

The returned certificate is valid for the next 24 hours and must be presented only whenthe server name in the TLS ClientHello matches the domain, and the special acme-tls/1 ALPN protocolhas been specified.

func (*Client)UpdateReg¶

func (c *Client) UpdateReg(ctxcontext.Context, acct *Account) (*Account,error)

UpdateReg updates an existing registration.It returns an updated account copy. The provided account is not modified.

The account's URI is ignored and the account URL associated withc.Key is used instead.

func (*Client)WaitAuthorization¶

func (c *Client) WaitAuthorization(ctxcontext.Context, urlstring) (*Authorization,error)

WaitAuthorization polls an authorization at the given URLuntil it is in one of the final states, StatusValid or StatusInvalid,the ACME CA responded with a 4xx error code, or the context is done.

It returns a non-nil Authorization only if its Status is StatusValid.In all other cases WaitAuthorization returns an error.If the Status is StatusInvalid, the returned error is of type *AuthorizationError.

func (*Client)WaitOrder¶

func (c *Client) WaitOrder(ctxcontext.Context, urlstring) (*Order,error)

WaitOrder polls an order from the given URL until it is in one of the final states,StatusReady, StatusValid or StatusInvalid, the CA responded with a non-retryable erroror the context is done.

It returns a non-nil Order only if its Status is StatusReady or StatusValid.In all other cases WaitOrder returns an error.If the Status is StatusInvalid, the returned error is of type *OrderError.

type Directory struct {// NonceURL indicates an endpoint where to fetch fresh nonce values from.NonceURLstring// RegURL is an account endpoint URL, allowing for creating new accounts.// Pre-RFC 8555 CAs also allow modifying existing accounts at this URL.RegURLstring// OrderURL is used to initiate the certificate issuance flow// as described inRFC 8555.OrderURLstring// AuthzURL is used to initiate identifier pre-authorization flow.// Empty string indicates the flow is unsupported by the CA.AuthzURLstring// CertURL is a new certificate issuance endpoint URL.// It is non-RFC 8555 compliant and is obsoleted by OrderURL.CertURLstring// RevokeURL is used to initiate a certificate revocation flow.RevokeURLstring// KeyChangeURL allows to perform account key rollover flow.KeyChangeURLstring// RenewalInfoURL allows to perform certificate renewal using the ACME// Renewal Information (ARI) Extension.RenewalInfoURLstring// Terms is a URI identifying the current terms of service.Termsstring// Website is an HTTP or HTTPS URL locating a website// providing more information about the ACME server.Websitestring// CAA consists of lowercase hostname elements, which the ACME server// recognises as referring to itself for the purposes of CAA record validation// as defined inRFC 6844.CAA []string// ExternalAccountRequired indicates that the CA requires for all account-related// requests to include external account binding information.ExternalAccountRequiredbool}

type Error struct {// StatusCode is The HTTP status code generated by the origin server.StatusCodeint// ProblemType is a URI reference that identifies the problem type,// typically in a "urn:acme:error:xxx" form.ProblemTypestring// Detail is a human-readable explanation specific to this occurrence of the problem.Detailstring// Instance indicates a URL that the client should direct a human user to visit// in order for instructions on how to agree to the updated Terms of Service.// In such an event CA sets StatusCode to 403, ProblemType to// "urn:ietf:params:acme:error:userActionRequired" and a Link header with relation// "terms-of-service" containing the latest TOS URL.Instancestring// Header is the original server error response headers.// It may be nil.Headerhttp.Header// Subproblems may contain more detailed information about the individual problems// that caused the error. This field is only sent byRFC 8555 compatible ACME// servers. Defined inRFC 8555 Section 6.7.1.Subproblems []Subproblem}

func (*Error)Error¶

func (e *Error) Error()string

type ExternalAccountBinding struct {// KID is the Key ID of the symmetric MAC key that the CA provides to// identify an external account from ACME.KIDstring// Key is the bytes of the symmetric key that the CA provides to identify// the account. Key must correspond to the KID.Key []byte}

func (*ExternalAccountBinding)String¶

func (e *ExternalAccountBinding) String()string

type KeyIDstring

type Order struct {// URI uniquely identifies an order.URIstring// Status represents the current status of the order.// It indicates which action the client should take.//// Possible values are StatusPending, StatusReady, StatusProcessing, StatusValid and StatusInvalid.// Pending means the CA does not believe that the client has fulfilled the requirements.// Ready indicates that the client has fulfilled all the requirements and can submit a CSR// to obtain a certificate. This is done with Client's CreateOrderCert.// Processing means the certificate is being issued.// Valid indicates the CA has issued the certificate. It can be downloaded// from the Order's CertURL. This is done with Client's FetchCert.// Invalid means the certificate will not be issued. Users should consider this order// abandoned.Statusstring// Expires is the timestamp after which CA considers this order invalid.Expirestime.Time// Identifiers contains all identifier objects which the order pertains to.Identifiers []AuthzID// NotBefore is the requested value of the notBefore field in the certificate.NotBeforetime.Time// NotAfter is the requested value of the notAfter field in the certificate.NotAftertime.Time// AuthzURLs represents authorizations to complete before a certificate// for identifiers specified in the order can be issued.// It also contains unexpired authorizations that the client has completed// in the past.//// Authorization objects can be fetched using Client's GetAuthorization method.//// The required authorizations are dictated by CA policies.// There may not be a 1:1 relationship between the identifiers and required authorizations.// Required authorizations can be identified by their StatusPending status.//// For orders in the StatusValid or StatusInvalid state these are the authorizations// which were completed.AuthzURLs []string// FinalizeURL is the endpoint at which a CSR is submitted to obtain a certificate// once all the authorizations are satisfied.FinalizeURLstring// CertURL points to the certificate that has been issued in response to this order.CertURLstring// The error that occurred while processing the order as received from a CA, if any.Error *Error}

type OrderError struct {OrderURLstringStatusstring}

func (*OrderError)Error¶

func (oe *OrderError) Error()string

type OrderOption interface {// contains filtered or unexported methods}

funcWithOrderNotAfter¶

func WithOrderNotAfter(ttime.Time)OrderOption

WithOrderNotAfter sets order's NotAfter field.

funcWithOrderNotBefore¶

func WithOrderNotBefore(ttime.Time)OrderOption

WithOrderNotBefore sets order's NotBefore field.

funcWithOrderReplacesCert¶added inv1.84.0

func WithOrderReplacesCert(cert *x509.Certificate)OrderOption

WithOrderReplacesCert indicates that this Order is for a replacement of anexisting certificate.Seehttps://datatracker.ietf.org/doc/html/draft-ietf-acme-ari-03#section-5

funcWithOrderReplacesCertDER¶added inv1.84.0

func WithOrderReplacesCertDER(der []byte)OrderOption

WithOrderReplacesCertDER indicates that this Order is for a replacement ofan existing DER-encoded certificate.Seehttps://datatracker.ietf.org/doc/html/draft-ietf-acme-ari-03#section-5

type RenewalInfo struct {SuggestedWindowRenewalInfoWindow `json:"suggestedWindow"`ExplanationURLstring            `json:"explanationURL"`}

type RenewalInfoWindow struct {Starttime.Time `json:"start"`Endtime.Time `json:"end"`}

type Subproblem struct {// Type is a URI reference that identifies the problem type,// typically in a "urn:acme:error:xxx" form.Typestring// Detail is a human-readable explanation specific to this occurrence of the problem.Detailstring// Instance indicates a URL that the client should direct a human user to visit// in order for instructions on how to agree to the updated Terms of Service.// In such an event CA sets StatusCode to 403, Type to// "urn:ietf:params:acme:error:userActionRequired", and adds a Link header with relation// "terms-of-service" containing the latest TOS URL.Instancestring// Identifier may contain the ACME identifier that the error is for.Identifier *AuthzID}

func (Subproblem)String¶

func (spSubproblem) String()string