acme

package
v0.3.2 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package acme is the ACME server (RFC 8555) for the internal CAs (PHASE2). By default it runs behind a reverse proxy that terminates TLS (owner Q1): plain HTTP on acme.listen, requests only from acme.trusted_proxies. With acme.tls_issuer (v0.2.2) the server's own TLS listener serves it and the peer is the client (Options.Direct). Every URL is built from acme.base_url.

Every request body is attacker input (security.md): the JWS is read by internal/acme/jose, payloads are decoded into fixed structures, sizes are limited. Issuance goes through ca.Engine.Issue with the domain policy (ADR-19); validation connects only where security.md allows.

Index

Constants

View Source
const (
	ActionAccountCreate     = "acme.account.create"
	ActionAccountUpdate     = "acme.account.update"
	ActionAccountDeactivate = "acme.account.deactivate"
	ActionAccountKeyChange  = "acme.account.key_change"
	ActionAccountApprove    = "acme.account.approve"
	ActionOrderCreate       = "acme.order.create"
	ActionChallenge         = "acme.challenge.validate"
	ActionAuthzDeactivate   = "acme.authz.deactivate"
	ActionNameDecide        = "acme.name.decide"
	ActionEABCreate         = "acme.eab.create"
)

Audit actions of the ACME server.

View Source
const (
	DefaultEABDays = 7
)

EAB key validity bounds in days.

View Source
const EABAlgorithm = "hs256"

EABAlgorithm names the MAC keys in the key ring.

View Source
const (

	// ValidAuthzLifetime: how long a passed challenge counts for new orders
	// (owner Q6).
	ValidAuthzLifetime = 7 * 24 * time.Hour
)

Limits.

Variables

View Source
var DefaultLimits = Limits{OrdersPerAccount: 300, FailedPerName: 5, AccountsPerIP: 10}

DefaultLimits apply without settings.

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound: no such account, name or key.

Functions

This section is empty.

Types

type AccountInfo

type AccountInfo struct {
	ID, Status, Thumbprint, CreatedAt, CreatedIP string
	Contacts                                     []string
	Approved                                     bool
	ApprovedBy, ApprovedAt, EABKey               string
	Predecessor                                  *predecessor.Policy
	EffectivePredecessor                         predecessor.Policy
}

AccountInfo is an ACME account as the UI shows it.

type EABKeyInfo

type EABKeyInfo struct {
	ID, Label, ExpiresAt, UsedAt, UsedBy, CreatedBy, CreatedAt string
}

EABKeyInfo is an EAB key without its secret.

type HTTP01Checker added in v0.3.0

type HTTP01Checker struct {
	// contains filtered or unexported fields
}

HTTP01Checker is the http-01 fetch of this validator for other proofs of control – the agent enrollment (ADR-18, docs/PHASE3.md §6.1) – with exactly the same rules: port 80 only, redirects only to 80/443 of the same host, one resolution through acme.resolver and a connection to exactly the checked address, the domain's address policy, short timeouts, 1 KiB.

func NewHTTP01Checker added in v0.3.0

func NewHTTP01Checker(resolver string, log *slog.Logger) *HTTP01Checker

NewHTTP01Checker returns a checker that resolves through resolver ("": the system resolver; IP or IP:port as acme.resolver).

func (*HTTP01Checker) Check added in v0.3.0

func (c *HTTP01Checker) Check(ctx context.Context, host, token, want, policy string) error

Check fetches http://host/.well-known/acme-challenge/<token> and compares the answer with want. policy is the address policy of the domain that covers host ("internal" or "public"). The error says what failed – never what the target answered.

func (*HTTP01Checker) SetNetwork added in v0.3.0

func (c *HTTP01Checker) SetNetwork(dial func(ctx context.Context, network, addr string) (net.Conn, error),
	lookupIP func(ctx context.Context, host string) ([]netip.Addr, error))

SetNetwork replaces the network edges – for tests only, never the rules.

type Limits

type Limits struct {
	OrdersPerAccount int // new orders per account
	FailedPerName    int // failed validations per name
	AccountsPerIP    int // new accounts per client address (IPv6: per /64)
}

Limits are the rate limits per hour (PHASE2 step 11).

type NameInfo

type NameInfo struct {
	Name, Status, RequestedBy, RequestedAt, DecidedBy, DecidedAt string
}

NameInfo is a name under the approval level "new_name".

type NewEABKey

type NewEABKey struct {
	KID, HMAC, ExpiresAt string
}

NewEABKey is a fresh key: the MAC is shown once and never stored in plain text.

type Options

type Options struct {
	Engine *ca.Engine // the tenant's engine; its PKI writer holds the ACME tables
	// BaseURL, TrustedProxies and Resolver as in config.ACME.
	BaseURL, TrustedProxies, Resolver string
	// Direct: the server's own TLS listener serves ACME (acme.tls_issuer,
	// v0.2.2). Every peer may connect, TrustedProxies and X-Forwarded-For
	// are ignored, and the peer is the client address (rate limits, audit).
	Direct bool
	Clock  clock.Clock
	Log    *slog.Logger
	// Rand for tokens and IDs; nil = crypto/rand.
	Rand io.Reader
	// Limits returns the tenant's rate limits (its settings); nil or an
	// error = DefaultLimits.
	Limits func(ctx context.Context) (Limits, error)
}

Options configure the server.

type OrderInfo

type OrderInfo struct {
	ID, AccountID, Status, CertificateID, CreatedAt, Error string
	Identifiers                                            []string
}

OrderInfo is an ACME order as the UI shows it.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the ACME server of one tenant.

func New

func New(opt Options) (*Server, error)

New prepares the server; it doesn't listen.

func (*Server) Account

func (s *Server) Account(ctx context.Context, who keys.Who, id string) (*AccountInfo, error)

Account returns one account.

func (*Server) Accounts

func (s *Server) Accounts(ctx context.Context, who keys.Who) ([]AccountInfo, error)

Accounts lists the newest accounts.

func (*Server) ApproveAccount

func (s *Server) ApproveAccount(ctx context.Context, id string, who keys.Who) error

ApproveAccount lets an account order under the approval level "account".

func (*Server) BaseURL

func (s *Server) BaseURL() string

BaseURL is the ACME base URL; the directory is BaseURL + "/directory".

func (*Server) Close

func (s *Server) Close()

Close stops new work and waits for running validations.

func (*Server) CreateEABKey

func (s *Server) CreateEABKey(ctx context.Context, label string, days int, who keys.Who) (*NewEABKey, error)

CreateEABKey makes an EAB key (owner Q2): 256 random bits, encrypted with the key ring (purpose acme-eab, so it can't be read as another key), usable once until it expires. It needs ca.manage with a fresh second factor and an unsealed server.

func (*Server) DecideName

func (s *Server) DecideName(ctx context.Context, name string, approve bool, who keys.Who) error

DecideName approves or refuses a name waiting under "new_name" ("dns:x" or "ip:x"). Approving a name nobody asked for yet is allowed too.

func (*Server) EABKeys

func (s *Server) EABKeys(ctx context.Context, who keys.Who) ([]EABKeyInfo, error)

EABKeys lists the newest keys.

func (*Server) ExpireStale

func (s *Server) ExpireStale(ctx context.Context) error

ExpireStale marks expired orders and authorizations (a job, every few minutes); reads bring a single object up to date on their own.

func (*Server) Names

func (s *Server) Names(ctx context.Context, who keys.Who) ([]NameInfo, error)

Names lists waiting names first.

func (*Server) Orders

func (s *Server) Orders(ctx context.Context, who keys.Who) ([]OrderInfo, error)

Orders lists the newest orders.

func (*Server) Pending

func (s *Server) Pending(ctx context.Context) (accounts, names int64, err error)

Pending counts what waits for an admin (dashboard).

func (*Server) ProcessPending

func (s *Server) ProcessPending(ctx context.Context) error

ProcessPending issues the orders that wait – after the unseal and every minute (a finalize while sealed, or a crash between finalize and issue).

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP checks where the request comes from, then dispatches. Every answer carries a fresh nonce and the directory link (RFC 8555 §6.5, §7.1).

func (*Server) SetAccountPredecessor added in v0.3.1

func (s *Server) SetAccountPredecessor(ctx context.Context, id string, policy *predecessor.Policy, who keys.Who) error

SetAccountPredecessor changes the non-agent account override. Nil restores the tenant default. It needs the same admin+step-up as other ACME admin actions.

func (*Server) SetNetwork added in v0.3.0

func (s *Server) SetNetwork(dial func(context.Context, string, string) (net.Conn, error), lookupIP func(context.Context, string) ([]netip.Addr, error))

SetNetwork replaces validation network edges for integration tests. Address, port and redirect policy checks still run unchanged.

func (*Server) Waiting

func (s *Server) Waiting(ctx context.Context) (int64, error)

Waiting counts the orders that wait for the unseal (dashboard).

Directories

Path Synopsis
Package jose reads the JSON Web Signatures of ACME requests (RFC 7515, RFC 8555 §6.2) – own code for the parsing and the rules, cryptography only from the standard library (owner Q3, 2026-10-22).
Package jose reads the JSON Web Signatures of ACME requests (RFC 7515, RFC 8555 §6.2) – own code for the parsing and the rules, cryptography only from the standard library (owner Q3, 2026-10-22).

Jump to

Keyboard shortcuts

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