acmeserver

Documentation

Index

• type ACMEChallenge
  • func (c ACMEChallenge) String() string
  • func (c *ACMEChallenge) UnmarshalJSON(b []byte) error
• type ACMEChallenges
• type Handler
  • func (Handler) CaddyModule() caddy.ModuleInfo
  • func (ash Handler) Cleanup() error
  • func (ash *Handler) Provision(ctx caddy.Context) error
  • func (ash Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
• type Policy
• type RuleSet

Types

type ACMEChallenge

type ACMEChallenge string

ACMEChallenge is an opaque string that represents supported ACME challenges.

const (
	HTTP_01     ACMEChallenge = "http-01"
	DNS_01      ACMEChallenge = "dns-01"
	TLS_ALPN_01 ACMEChallenge = "tls-alpn-01"
)

func (ACMEChallenge) String

func (c ACMEChallenge) String() string

String returns a string representation of the challenge.

func (*ACMEChallenge) UnmarshalJSON

func (c *ACMEChallenge) UnmarshalJSON(b []byte) error

The unmarshaller first marshals the value into a string. Then it trims any space around it and lowercase it for normaliztion. The method does not and should not validate the value within accepted enums.

type ACMEChallenges

type ACMEChallenges []ACMEChallenge

ACMEChallenges is a list of ACME challenges.

type Handler

type Handler struct {
	// The ID of the CA to use for signing. This refers to
	// the ID given to the CA in the `pki` app. If omitted,
	// the default ID is "local".
	CA string `json:"ca,omitempty"`

	// The lifetime for issued certificates
	Lifetime caddy.Duration `json:"lifetime,omitempty"`

	// The hostname or IP address by which ACME clients
	// will access the server. This is used to populate
	// the ACME directory endpoint. If not set, the Host
	// header of the request will be used.
	// COMPATIBILITY NOTE / TODO: This property may go away in the
	// future. Do not rely on this property long-term; check release notes.
	Host string `json:"host,omitempty"`

	// The path prefix under which to serve all ACME
	// endpoints. All other requests will not be served
	// by this handler and will be passed through to
	// the next one. Default: "/acme/".
	// COMPATIBILITY NOTE / TODO: This property may go away in the
	// future, as it is currently only required due to
	// limitations in the underlying library. Do not rely
	// on this property long-term; check release notes.
	PathPrefix string `json:"path_prefix,omitempty"`

	// If true, the CA's root will be the issuer instead of
	// the intermediate. This is NOT recommended and should
	// only be used when devices/clients do not properly
	// validate certificate chains. EXPERIMENTAL: Might be
	// changed or removed in the future.
	SignWithRoot bool `json:"sign_with_root,omitempty"`

	// The addresses of DNS resolvers to use when looking up
	// the TXT records for solving DNS challenges.
	// It accepts [network addresses](/docs/conventions#network-addresses)
	// with port range of only 1. If the host is an IP address,
	// it will be dialed directly to resolve the upstream server.
	// If the host is not an IP address, the addresses are resolved
	// using the [name resolution convention](https://golang.org/pkg/net/#hdr-Name_Resolution)
	// of the Go standard library. If the array contains more
	// than 1 resolver address, one is chosen at random.
	Resolvers []string `json:"resolvers,omitempty"`

	// Specify the set of enabled ACME challenges. An empty or absent value
	// means all challenges are enabled. Accepted values are:
	// "http-01", "dns-01", "tls-alpn-01"
	Challenges ACMEChallenges `json:"challenges,omitempty" `

	// The policy to use for issuing certificates
	Policy *Policy `json:"policy,omitempty"`
	// contains filtered or unexported fields
}

Handler is an ACME server handler.

func (Handler) CaddyModule

func (Handler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (Handler) Cleanup

func (ash Handler) Cleanup() error

Cleanup implements caddy.CleanerUpper and closes any idle databases.

func (*Handler) Provision

func (ash *Handler) Provision(ctx caddy.Context) error

Provision sets up the ACME server handler.

func (Handler) ServeHTTP

func (ash Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

type Policy

type Policy struct {
	// If a rule set is configured to allow a certain type of name,
	// all other types of names are automatically denied.
	Allow *RuleSet `json:"allow,omitempty"`

	// If a rule set is configured to deny a certain type of name,
	// all other types of names are still allowed.
	Deny *RuleSet `json:"deny,omitempty"`

	// If set to true, the ACME server will allow issuing wildcard certificates.
	AllowWildcardNames bool `json:"allow_wildcard_names,omitempty"`
}

Policy defines the criteria for the ACME server of when to issue a certificate. Refer to the [Certificate Issuance Policy](https://smallstep.com/docs/step-ca/policies/) on Smallstep website for the evaluation criteria.

type RuleSet

type RuleSet struct {
	// Domains is a list of DNS domains that are allowed to be issued.
	// It can be in the form of FQDN for specific domain name, or
	// a wildcard domain name format, e.g. *.example.com, to allow
	// sub-domains of a domain.
	Domains []string `json:"domains,omitempty"`

	// IP ranges in the form of CIDR notation or specific IP addresses
	// to be approved or denied for certificates. Non-CIDR IP addresses
	// are matched exactly.
	IPRanges []string `json:"ip_ranges,omitempty"`
}

RuleSet is the specific set of SAN criteria for a certificate to be issued or denied.