acmeclient

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2022 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package acmeclient provides a RawChainSource to acquire a signed exchange certificate using the ACME protocol. The ACME protocol allows a server to obtain a certificate automatically, without any human intervention. To learn about how it works, see https://letsencrypt.org/how-it-works/.

Client is the ACME client that behaves as a RawChainSource, typically used with Manager or Augmentor. The consumer code is recommended to use it with DiskCache, so the admin can retrieve the acquired certificate from the disk:

m := certmanager.Manager(certmanager.Config{
	RawChainSource: acmeclient.NewClient(acmeclient.Config{
		...
	},
	OCSPRespSource: certmanager.DefaultOCSPClient,
	Cache: certmanager.NewDiskCache(certmanager.DiskCacheConfig{
		CertPath: "/tmp/acme/cert.pem",
		LockPath: "/tmp/acme/.lock",
	},
})

Client is capable of responding to "challenges," which the ACME server poses to the requestor to verify it has the control over the requested domain. See Config for how to set up the challenge responder.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	LegoClient      *lego.Client
	CertSignRequest *x509.CertificateRequest
	FetchTiming     certmanager.FetchTiming
}

Client acquires a signed exchange certificate using the ACME protocol as a certmanager.RawChainSource.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient creates and initializes a new Client with config.

func (*Client) Fetch

func (c *Client) Fetch(chain *certchain.RawChain, now func() time.Time) (newChain *certchain.RawChain, nextRun futureevent.Event, err error)

Fetch acquires a new RawChain from the ACME server if the chain is either expired or about to expire as compared to certRenewalInterval.

type Config

type Config struct {
	// CertSignRequest is the Certificate Signing Request (CSR) sent over the
	// ACME protocol.
	CertSignRequest *x509.CertificateRequest

	// User provides the user information for the ACME request.
	User *User

	// DiscoveryURL is the Discovery Resource URL provided by the Certificate
	// Authority to make ACME requests.
	DiscoveryURL string

	// EABKid is the key identifier from ACME CA. Used for External Account
	// Binding.
	EABKid string

	// EABHmac is the MAC Key from ACME CA. Used for External Account Binding.
	// Should be in Base64 URL Encoding without padding format.
	EABHmac string

	// HTTPChallengePort is the HTTP challenge port used for the ACME HTTP
	// challenge.
	//
	// Remember you need to proxy challenge traffic. See Port Usage above.
	HTTPChallengePort int

	// HTTPWebRootDir is the web root directory where the ACME HTTP challenge
	// token will be deposited.
	HTTPWebRootDir string

	// TLSChallengePort is the TLS challenge port used for the ACME TLS
	// challenge.
	//
	// Remember you need to proxy challenge traffic. See Port Usage above.
	TLSChallengePort int

	// DNSProvider is the ACME DNS Provider used for the challenge. It is
	// specified by the Lego config code.
	//
	// The binary must be built with `-tags dns01` to use the DNS challenge.
	// If DNSProvider is set non-empty in a binary without that build option,
	// NewClient will fail with an error.
	//
	// See https://go-acme.github.io/lego/dns/ for the DNS Provider list.
	DNSProvider string

	// ShouldRegister specifies whether the ACME user needs to register with
	// the Certificate Authority.
	ShouldRegister bool

	// FetchTiming controls the frequency of checking for the certificate.
	// nil implies certmanager.FetchHourly.
	FetchTiming certmanager.FetchTiming
}

Config configures Client. It contains information to request a certificate to the Certificate Authority (CA) using the ACME protocol.

HTTPChallengePort, HTTPWebRootDir, TLSChallengePort and DNSProvider specify how Client responds to challenges from the ACME server. The ACME standard defines three types of challenges, namely HTTP, DNS and TLS, and each field configures one of them. Only one of the four fields is expected to be set. For wildcard domains, the DNS challenge is the only option thus DNSProvider must be set.

https://letsencrypt.org/docs/challenge-types/ describes these challenges in greater detail.

Port Usage

Client uses HTTPChallengePort or TLSChallengePort, while the ACME protocol requires the HTTP and TLS challenge responders to listen on the standard ports (80 and 443), because webpackager isn't designed to run as root thus can't bind a listener to the privileged ports. Keep in mind that you need to proxy challenge traffic to the custom port you specified.

type User

type User struct {
	Email        string
	Registration *registration.Resource
	Key          crypto.PrivateKey
}

User implements registration.User (go-acme/lego).

func NewUser

func NewUser(email string, key crypto.PrivateKey) *User

NewUser creates a new User.

func (*User) GetEmail

func (u *User) GetEmail() string

GetEmail returns the email address associated with the User.

func (*User) GetPrivateKey

func (u *User) GetPrivateKey() crypto.PrivateKey

GetPrivateKey returns the private key associated with the User.

func (*User) GetRegistration

func (u *User) GetRegistration() *registration.Resource

GetRegistration returns the registration resource associated with the User.

func (*User) SetRegistration

func (u *User) SetRegistration(r *registration.Resource)

SetRegistration sets the registration resource associated with the User.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL