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) 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)
- 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 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" 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 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
// 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 ¶
The directory 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
FetchRaw 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) 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.
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
// 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:"-"`
}
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 SubProblem ¶ added in v3.1.0
type SubProblem struct {
Type string `json:"type"`
Detail string `json:"detail"`
Identifier Identifier `json:"identifier"`
}