Documentation ¶
Index ¶
- Constants
- Variables
- func EncodeDNS01KeyAuthorization(keyAuth string) string
- func JWKThumbprint(pub crypto.PublicKey) (string, error)
- type Account
- type Authorization
- type AutoCert
- type Challenge
- type Client
- func (c Client) AccountKeyChange(account Account, newPrivateKey crypto.Signer) (Account, error)
- func (c Client) DeactivateAccount(account Account) (Account, error)
- func (c Client) DeactivateAuthorization(account Account, authURL string) (Authorization, error)
- func (c Client) Directory() Directory
- func (c Client) Fetch(account Account, requestURL string, result interface{}, expectedStatus ...int) error
- func (c Client) FetchAllCertificates(account Account, certificateURL string) (map[string][]*x509.Certificate, error)
- func (c Client) FetchAuthorization(account Account, authURL string) (Authorization, error)
- func (c Client) FetchCertificates(account Account, certificateURL string) ([]*x509.Certificate, error)
- func (c Client) FetchChallenge(account Account, challengeURL string) (Challenge, error)
- func (c Client) FetchOrder(account Account, orderURL string) (Order, error)
- func (c Client) FetchOrderList(account Account) (OrderList, error)
- func (c Client) FinalizeOrder(account Account, order Order, csr *x509.CertificateRequest) (Order, error)
- func (c Client) GetRenewalInfo(cert, issuer *x509.Certificate, hash crypto.Hash) (RenewalInfo, error)
- func (c Client) NewAccount(privateKey crypto.Signer, onlyReturnExisting, termsOfServiceAgreed bool, ...) (Account, error)
- func (c Client) NewAccountOptions(privateKey crypto.Signer, options ...NewAccountOptionFunc) (Account, error)
- func (c Client) NewOrder(account Account, identifiers []Identifier) (Order, error)
- func (c Client) NewOrderDomains(account Account, domains ...string) (Order, error)
- func (c Client) RevokeCertificate(account Account, cert *x509.Certificate, key crypto.Signer, reason int) error
- func (c Client) UpdateAccount(account Account, contact ...string) (Account, error)
- func (c Client) UpdateChallenge(account Account, challenge Challenge) (Challenge, error)
- func (c Client) UpdateRenewalInfo(account Account, cert, issuer *x509.Certificate, hash crypto.Hash, ...) error
- type Directory
- type ExternalAccountBinding
- type HostCheck
- type Identifier
- type KeyID
- type NewAccountOptionFunc
- type NewAccountRequest
- type OptionFunc
- func WithAcceptLanguage(acceptLanguage string) OptionFunc
- func WithHTTPClient(httpClient *http.Client) OptionFunc
- func WithHTTPTimeout(duration time.Duration) OptionFunc
- func WithInsecureSkipVerify() OptionFunc
- func WithRetryCount(retryCount int) OptionFunc
- func WithRootCerts(pool *x509.CertPool) OptionFunc
- func WithUserAgentSuffix(userAgentSuffix string) OptionFunc
- type Order
- type OrderList
- type Problem
- type RenewalInfo
- type SubProblem
Constants ¶
const ( // LetsEncryptProduction holds the production directory url LetsEncryptProduction = "https://acme-v02.api.letsencrypt.org/directory" // LetsEncryptStaging holds the staging directory url LetsEncryptStaging = "https://acme-staging-v02.api.letsencrypt.org/directory" // ZeroSSLProduction holds the ZeroSSL directory url ZeroSSLProduction = "https://acme.zerossl.com/v2/DV90" )
const ( ChallengeTypeDNS01 = "dns-01" ChallengeTypeDNSAccount01 = "dns-account-01" ChallengeTypeHTTP01 = "http-01" ChallengeTypeTLSALPN01 = "tls-alpn-01" // ChallengeTypeTLSSNI01 is deprecated and should not be used. // See: https://community.letsencrypt.org/t/important-what-you-need-to-know-about-tls-sni-validation-issues/50811 ChallengeTypeTLSSNI01 = "tls-sni-01" )
Different possible challenge types provided by an ACME server. See https://tools.ietf.org/html/rfc8555#section-9.7.8
const ( ReasonUnspecified = iota // 0 ReasonKeyCompromise // 1 ReasonCaCompromise // 2 ReasonAffiliationChanged // 3 ReasonSuperseded // 4 ReasonCessationOfOperation // 5 ReasonCertificateHold // 6 ReasonRemoveFromCRL // 8 ReasonPrivilegeWithdrawn // 9 ReasonAaCompromise // 10 )
Constants used for certificate revocation, used for RevokeCertificate See https://tools.ietf.org/html/rfc5280#section-5.3.1
Variables ¶
var ( // ErrRenewalInfoNotSupported is returned by Client.GetRenewalInfo and Client.UpdateRenewalInfo if the renewal info // entry isn't present on the acme directory (ie, it's not supported by the acme server) ErrRenewalInfoNotSupported = errors.New("renewal information endpoint not") )
var ErrUnsupportedKey = errors.New("acme: unknown key type; only RSA and ECDSA are supported")
ErrUnsupportedKey is returned when an unsupported key type is encountered.
Functions ¶
func EncodeDNS01KeyAuthorization ¶
EncodeDNS01KeyAuthorization encodes a key authorization and provides a value to be put in the TXT record for the _acme-challenge DNS entry.
func JWKThumbprint ¶
JWKThumbprint creates a JWK thumbprint out of pub as specified in https://tools.ietf.org/html/rfc7638.
Types ¶
type Account ¶
type Account struct { Status string `json:"status"` Contact []string `json:"contact"` Orders string `json:"orders"` // Provided by the Location http header when creating a new account or fetching an existing account. URL string `json:"-"` // The private key used to create or fetch the account. // Not fetched from server. PrivateKey crypto.Signer `json:"-"` // Thumbprint is the SHA-256 digest JWK_Thumbprint of the account key. // See https://tools.ietf.org/html/rfc8555#section-8.1 Thumbprint string `json:"-"` // ExternalAccountBinding is populated when using the NewAcctOptExternalAccountBinding option for NewAccountOption // and is otherwise empty. Not populated when account is fetched or created otherwise. ExternalAccountBinding ExternalAccountBinding `json:"-"` }
Account structure representing fields in an account object. See https://tools.ietf.org/html/rfc8555#section-7.1.2 See also https://tools.ietf.org/html/rfc8555#section-9.7.1
type Authorization ¶
type Authorization struct { Identifier Identifier `json:"identifier"` Status string `json:"status"` Expires time.Time `json:"expires"` Challenges []Challenge `json:"challenges"` Wildcard bool `json:"wildcard"` // For convenience access to the provided challenges ChallengeMap map[string]Challenge `json:"-"` ChallengeTypes []string `json:"-"` URL string `json:"-"` }
Authorization object returned when fetching an authorization in an order. See https://tools.ietf.org/html/rfc8555#section-7.1.4
type AutoCert ¶
type AutoCert struct { // Acme directory Url // If nil, uses `LetsEncryptStaging` DirectoryURL string // Options contains the options used for creating the acme client Options []OptionFunc // A function to check whether a host is allowed or not // If nil, all hosts allowed // Use `WhitelistHosts(hosts ...string)` for a simple white list of hostnames HostCheck HostCheck // Cache dir to store account data and certificates // If nil, does not write cache data to file CacheDir string // When using a staging environment, include a root certificate for verification purposes RootCert string // Called before updating challenges PreUpdateChallengeHook func(Account, Challenge) // contains filtered or unexported fields }
AutoCert is a stateful certificate manager for issuing certificates on connecting hosts
func (*AutoCert) GetCertificate ¶
func (m *AutoCert) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate implements a tls.Config.GetCertificate hook
type Challenge ¶
type Challenge struct { Type string `json:"type"` URL string `json:"url"` Status string `json:"status"` Validated string `json:"validated"` Error Problem `json:"error"` // Based on the challenge used Token string `json:"token"` KeyAuthorization string `json:"keyAuthorization"` // Authorization url provided by the rel="up" Link http header AuthorizationURL string `json:"-"` }
Challenge object fetched in an authorization or directly from the challenge url. See https://tools.ietf.org/html/rfc8555#section-7.1.5
type Client ¶
type Client struct { // The amount of total time the Client will wait at most for a challenge to be updated or a certificate to be issued. // Default 30 seconds if duration is not set or if set to 0. PollTimeout time.Duration // The time between checking if a challenge has been updated or a certificate has been issued. // Default 0.5 seconds if duration is not set or if set to 0. PollInterval time.Duration // IgnorePolling does not use any simple polling in order finalisation IgnorePolling bool // IgnoreRetryAfter does not use the retry-after header in order finalisation IgnoreRetryAfter bool // contains filtered or unexported fields }
Client structure to interact with an ACME server. This is typically how most, if not all, of the communication between the client and server occurs.
func NewClient ¶
func NewClient(directoryURL string, options ...OptionFunc) (Client, error)
NewClient creates a new acme client given a valid directory url.
func (Client) AccountKeyChange ¶
AccountKeyChange rolls over an account to a new key.
func (Client) DeactivateAccount ¶
DeactivateAccount deactivates a given account.
func (Client) DeactivateAuthorization ¶
func (c Client) DeactivateAuthorization(account Account, authURL string) (Authorization, error)
DeactivateAuthorization deactivate a provided authorization url from an order.
func (Client) Directory ¶
Directory is the object returned by the client connecting to a directory url.
func (Client) Fetch ¶ added in v3.1.0
func (c Client) Fetch(account Account, requestURL string, result interface{}, expectedStatus ...int) error
Fetch is a helper function to assist with POST-AS-GET requests
func (Client) FetchAllCertificates ¶ added in v3.1.0
func (c Client) FetchAllCertificates(account Account, certificateURL string) (map[string][]*x509.Certificate, error)
FetchAllCertificates downloads a certificate chain from a url given in an order certificate, as well as any alternate certificates if provided. Returns a mapping of certificate urls to the certificate chain.
func (Client) FetchAuthorization ¶
func (c Client) FetchAuthorization(account Account, authURL string) (Authorization, error)
FetchAuthorization fetches an authorization from an authorization url provided in an order.
func (Client) FetchCertificates ¶
func (c Client) FetchCertificates(account Account, certificateURL string) ([]*x509.Certificate, error)
FetchCertificates downloads a certificate chain from a url given in an order certificate.
func (Client) FetchChallenge ¶
FetchChallenge fetches an existing challenge from the given url.
func (Client) FetchOrder ¶
FetchOrder fetches an existing order given an order url.
func (Client) FetchOrderList ¶ added in v3.1.0
FetchOrderList fetches a list of orders from the account url provided in the account Orders field
func (Client) FinalizeOrder ¶
func (c Client) FinalizeOrder(account Account, order Order, csr *x509.CertificateRequest) (Order, error)
FinalizeOrder indicates to the acme server that the client considers an order complete and "finalizes" it. If the server believes the authorizations have been filled successfully, a certificate should then be available. This function assumes that the order status is "ready".
func (Client) GetRenewalInfo ¶ added in v3.4.0
func (c Client) GetRenewalInfo(cert, issuer *x509.Certificate, hash crypto.Hash) (RenewalInfo, error)
GetRenewalInfo returns the renewal information (if present and supported by the ACME server), and a Retry-After time if indicated in the http response header.
func (Client) NewAccount ¶
func (c Client) NewAccount(privateKey crypto.Signer, onlyReturnExisting, termsOfServiceAgreed bool, contact ...string) (Account, error)
NewAccount registers a new account with the acme service Note this function is essentially deprecated and only present for backwards compatibility. New programs should implement NewAccountOptions instead.
func (Client) NewAccountOptions ¶ added in v3.2.0
func (c Client) NewAccountOptions(privateKey crypto.Signer, options ...NewAccountOptionFunc) (Account, error)
NewAccountOptions registers an account with an acme server with the provided options.
func (Client) NewOrder ¶
func (c Client) NewOrder(account Account, identifiers []Identifier) (Order, error)
NewOrder initiates a new order for a new certificate.
func (Client) NewOrderDomains ¶
NewOrderDomains is a wrapper for NewOrder(AcmeAccount, []AcmeIdentifiers) Creates a dns identifier for each provided domain
func (Client) RevokeCertificate ¶
func (c Client) RevokeCertificate(account Account, cert *x509.Certificate, key crypto.Signer, reason int) error
RevokeCertificate revokes a given certificate given the certificate key or account key, and a reason.
func (Client) UpdateAccount ¶
UpdateAccount updates an existing account with the acme service.
func (Client) UpdateChallenge ¶
UpdateChallenge responds to a challenge to indicate to the server to complete the challenge.
func (Client) UpdateRenewalInfo ¶ added in v3.4.0
func (c Client) UpdateRenewalInfo(account Account, cert, issuer *x509.Certificate, hash crypto.Hash, replaced bool) error
UpdateRenewalInfo sends a request to the acme server to indicate the renewal info is updated. replaced should always be true.
type Directory ¶
type Directory struct { NewNonce string `json:"newNonce"` // url to new nonce endpoint NewAccount string `json:"newAccount"` // url to new account endpoint NewOrder string `json:"newOrder"` // url to new order endpoint NewAuthz string `json:"newAuthz"` // url to new authz endpoint RevokeCert string `json:"revokeCert"` // url to revoke cert endpoint KeyChange string `json:"keyChange"` // url to key change endpoint RenewalInfo string `json:"renewalInfo"` // url to renewal info endpoint // meta object containing directory metadata Meta struct { TermsOfService string `json:"termsOfService"` Website string `json:"website"` CaaIdentities []string `json:"caaIdentities"` ExternalAccountRequired bool `json:"externalAccountRequired"` } `json:"meta"` // Directory url provided when creating a new acme client. URL string `json:"-"` }
Directory object as returned from the client's directory url upon creation of client. See https://tools.ietf.org/html/rfc8555#section-7.1.1
type ExternalAccountBinding ¶ added in v3.2.0
type ExternalAccountBinding struct { KeyIdentifier string `json:"-"` MacKey string `json:"-"` Algorithm string `json:"-"` HashFunc crypto.Hash `json:"-"` }
ExternalAccountBinding holds the key identifier and mac key provided for use in servers that support/require external account binding. The MacKey is a base64url-encoded string. Algorithm is a "MAC-based algorithm" as per RFC8555. Typically this is either,
- "HS256" for HashFunc: crypto.SHA256
- "HS384" for HashFunc: crypto.SHA384
- "HS512" for HashFunc: crypto.SHA512
However this is dependant on the acme server in question and is provided here to give more options for future compatibility.
type HostCheck ¶
HostCheck function prototype to implement for checking hosts against before issuing certificates
func WhitelistHosts ¶
WhitelistHosts implements a simple whitelist HostCheck
type Identifier ¶
Identifier object used in order and authorization objects See https://tools.ietf.org/html/rfc8555#section-7.1.4
type KeyID ¶ added in v3.3.0
type KeyID string
KeyID is the account key identity provided by a CA during registration.
type NewAccountOptionFunc ¶ added in v3.2.0
NewAccountOptionFunc function prototype for passing options to NewClient
func NewAcctOptAgreeTOS ¶ added in v3.2.0
func NewAcctOptAgreeTOS() NewAccountOptionFunc
NewAcctOptAgreeTOS sets the new account request as agreeing to the terms of service
func NewAcctOptExternalAccountBinding ¶ added in v3.2.0
func NewAcctOptExternalAccountBinding(binding ExternalAccountBinding) NewAccountOptionFunc
NewAcctOptExternalAccountBinding adds an external account binding to the new account request Code adopted from jwsEncodeJSON
func NewAcctOptOnlyReturnExisting ¶ added in v3.2.0
func NewAcctOptOnlyReturnExisting() NewAccountOptionFunc
NewAcctOptOnlyReturnExisting sets the new client request to only return existing accounts
func NewAcctOptWithContacts ¶ added in v3.2.0
func NewAcctOptWithContacts(contacts ...string) NewAccountOptionFunc
NewAcctOptWithContacts adds contacts to a new account request
type NewAccountRequest ¶ added in v3.2.0
type NewAccountRequest struct { OnlyReturnExisting bool `json:"onlyReturnExisting"` TermsOfServiceAgreed bool `json:"termsOfServiceAgreed"` Contact []string `json:"contact,omitempty"` ExternalAccountBinding json.RawMessage `json:"externalAccountBinding"` }
NewAccountRequest object used for submitting a request for a new account. Primarily used with NewAccountOptionFunc
type OptionFunc ¶
OptionFunc function prototype for passing options to NewClient
func WithAcceptLanguage ¶
func WithAcceptLanguage(acceptLanguage string) OptionFunc
WithAcceptLanguage sets an Accept-Language header on http requests
func WithHTTPClient ¶
func WithHTTPClient(httpClient *http.Client) OptionFunc
WithHTTPClient Allows setting a custom http client for acme connections
func WithHTTPTimeout ¶
func WithHTTPTimeout(duration time.Duration) OptionFunc
WithHTTPTimeout sets a timeout on the http client used by the Client
func WithInsecureSkipVerify ¶
func WithInsecureSkipVerify() OptionFunc
WithInsecureSkipVerify sets InsecureSkipVerify on the http client transport tls client config used by the Client
func WithRetryCount ¶
func WithRetryCount(retryCount int) OptionFunc
WithRetryCount sets the number of times the acme client retries when receiving an api error (eg, nonce failures, etc). Default: 5
func WithRootCerts ¶ added in v3.2.1
func WithRootCerts(pool *x509.CertPool) OptionFunc
WithRootCerts sets the httpclient transport to use a given certpool for root certs
func WithUserAgentSuffix ¶
func WithUserAgentSuffix(userAgentSuffix string) OptionFunc
WithUserAgentSuffix appends a user agent suffix for http requests to acme resources
type Order ¶
type Order struct { Status string `json:"status"` Expires time.Time `json:"expires"` Identifiers []Identifier `json:"identifiers"` NotBefore time.Time `json:"notBefore"` NotAfter time.Time `json:"notAfter"` Error Problem `json:"error"` Authorizations []string `json:"authorizations"` Finalize string `json:"finalize"` Certificate string `json:"certificate"` // URL for the order object. // Provided by the rel="Location" Link http header URL string `json:"-"` // RetryAfter is the http Retry-After header from the order response RetryAfter time.Time `json:"-"` }
Order object returned when fetching or creating a new order. See https://tools.ietf.org/html/rfc8555#section-7.1.3
type OrderList ¶
type OrderList struct { Orders []string `json:"orders"` // Order list pagination, url to next orders. // Provided by the rel="next" Link http header Next string `json:"-"` }
OrderList of challenge objects.
type Problem ¶
type Problem struct { Type string `json:"type"` Detail string `json:"detail,omitempty"` Status int `json:"status,omitempty"` Instance string `json:"instance,omitempty"` SubProblems []SubProblem `json:"subproblems,omitempty"` }
Problem represents an error returned by an acme server.
type RenewalInfo ¶ added in v3.4.0
type RenewalInfo struct { SuggestedWindow struct { Start time.Time `json:"start"` End time.Time `json:"end"` } `json:"suggestedWindow"` ExplanationURL string `json:"explanationURL"` RetryAfter time.Time `json:"-"` }
RenewalInfo is returned by Client.GetRenewalInfo
type SubProblem ¶ added in v3.1.0
type SubProblem struct { Type string `json:"type"` Detail string `json:"detail"` Identifier Identifier `json:"identifier"` }