acme: github.com/eggsampler/acme Index | Files

package acme

import "github.com/eggsampler/acme"

Index

Package Files

account.go acme.go authorization.go autocert.go certificate.go challenge.go jws.go nonce.go options.go order.go problem.go types.go

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"
)
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

func EncodeDNS01KeyAuthorization Uses

func EncodeDNS01KeyAuthorization(keyAuth string) string

EncodeDNS01KeyAuthorization encodes a key authorization and provides a value to be put in the TXT record for the _acme-challenge DNS entry.

func JWKThumbprint Uses

func JWKThumbprint(pub crypto.PublicKey) (string, error)

JWKThumbprint creates a JWK thumbprint out of pub as specified in https://tools.ietf.org/html/rfc7638.

type Account Uses

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:"-"`
}

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 Uses

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 Uses

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 Uses

func (m *AutoCert) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate implements a tls.Config.GetCertificate hook

func (*AutoCert) HTTPHandler Uses

func (m *AutoCert) HTTPHandler(handler http.Handler) http.Handler

HTTPHandler Wraps a handler and provides serving of http-01 challenge tokens from /.well-known/acme-challenge/ If handler is nil, will redirect all traffic otherwise to https

type Challenge Uses

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 Uses

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 Uses

func NewClient(directoryURL string, options ...OptionFunc) (Client, error)

NewClient creates a new acme client given a valid directory url.

func (Client) AccountKeyChange Uses

func (c Client) AccountKeyChange(account Account, newPrivateKey crypto.Signer) (Account, error)

AccountKeyChange rolls over an account to a new key.

func (Client) DeactivateAccount Uses

func (c Client) DeactivateAccount(account Account) (Account, error)

DeactivateAccount deactivates a given account.

func (Client) DeactivateAuthorization Uses

func (c Client) DeactivateAuthorization(account Account, authURL string) (Authorization, error)

DeactivateAuthorization deactivate a provided authorization url from an order.

func (Client) Directory Uses

func (c Client) Directory() Directory

The directory object returned by the client connecting to a directory url.

func (Client) Fetch Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (c Client) FetchChallenge(account Account, challengeURL string) (Challenge, error)

FetchChallenge fetches an existing challenge from the given url.

func (Client) FetchOrder Uses

func (c Client) FetchOrder(account Account, orderURL string) (Order, error)

FetchOrder fetches an existing order given an order url.

func (Client) FetchOrderList Uses

func (c Client) FetchOrderList(account Account) (OrderList, error)

FetchOrderList fetches a list of orders from the account url provided in the account Orders field

func (Client) FinalizeOrder Uses

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 Uses

func (c Client) NewAccount(privateKey crypto.Signer, onlyReturnExisting, termsOfServiceAgreed bool, contact ...string) (Account, error)

NewAccount registers a new account with the acme service

func (Client) NewOrder Uses

func (c Client) NewOrder(account Account, identifiers []Identifier) (Order, error)

NewOrder initiates a new order for a new certificate.

func (Client) NewOrderDomains Uses

func (c Client) NewOrderDomains(account Account, domains ...string) (Order, error)

NewOrderDomains is a wrapper for NewOrder(AcmeAccount, []AcmeIdentifiers) Creates a dns identifier for each provided domain

func (Client) RevokeCertificate Uses

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 Uses

func (c Client) UpdateAccount(account Account, contact ...string) (Account, error)

UpdateAccount updates an existing account with the acme service.

func (Client) UpdateChallenge Uses

func (c Client) UpdateChallenge(account Account, challenge Challenge) (Challenge, error)

UpdateChallenge responds to a challenge to indicate to the server to complete the challenge.

type Directory Uses

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 HostCheck Uses

type HostCheck func(host string) error

HostCheck function prototype to implement for checking hosts against before issuing certificates

func WhitelistHosts Uses

func WhitelistHosts(hosts ...string) HostCheck

WhitelistHosts implements a simple whitelist HostCheck

type Identifier Uses

type Identifier struct {
    Type  string `json:"type"`
    Value string `json:"value"`
}

Identifier object used in order and authorization objects See https://tools.ietf.org/html/rfc8555#section-7.1.4

type OptionFunc Uses

type OptionFunc func(client *Client) error

OptionFunc function prototype for passing options to NewClient

func WithAcceptLanguage Uses

func WithAcceptLanguage(acceptLanguage string) OptionFunc

WithAcceptLanguage sets an Accept-Language header on http requests

func WithHTTPClient Uses

func WithHTTPClient(httpClient *http.Client) OptionFunc

WithHTTPClient Allows setting a custom http client for acme connections

func WithHTTPTimeout Uses

func WithHTTPTimeout(duration time.Duration) OptionFunc

WithHTTPTimeout sets a timeout on the http client used by the Client

func WithInsecureSkipVerify Uses

func WithInsecureSkipVerify() OptionFunc

WithInsecureSkipVerify sets InsecureSkipVerify on the http client transport tls client config used by the Client

func WithRetryCount Uses

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 WithUserAgentSuffix Uses

func WithUserAgentSuffix(userAgentSuffix string) OptionFunc

WithUserAgentSuffix appends a user agent suffix for http requests to acme resources

type Order Uses

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 Uses

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 Uses

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.

func (Problem) Error Uses

func (err Problem) Error() string

Returns a human readable error string.

type SubProblem Uses

type SubProblem struct {
    Type       string     `json:"type"`
    Detail     string     `json:"detail"`
    Identifier Identifier `json:"identifier"`
}

Package acme imports 27 packages (graph) and is imported by 3 packages. Updated 2020-09-29. Refresh now. Tools for package owners.