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
- Variables
- type AccountInfo
- type EABKeyInfo
- type HTTP01Checker
- type Limits
- type NameInfo
- type NewEABKey
- type Options
- type OrderInfo
- type Server
- func (s *Server) Account(ctx context.Context, who keys.Who, id string) (*AccountInfo, error)
- func (s *Server) Accounts(ctx context.Context, who keys.Who) ([]AccountInfo, error)
- func (s *Server) ApproveAccount(ctx context.Context, id string, who keys.Who) error
- func (s *Server) BaseURL() string
- func (s *Server) Close()
- func (s *Server) CreateEABKey(ctx context.Context, label string, days int, who keys.Who) (*NewEABKey, error)
- func (s *Server) DecideName(ctx context.Context, name string, approve bool, who keys.Who) error
- func (s *Server) EABKeys(ctx context.Context, who keys.Who) ([]EABKeyInfo, error)
- func (s *Server) ExpireStale(ctx context.Context) error
- func (s *Server) Names(ctx context.Context, who keys.Who) ([]NameInfo, error)
- func (s *Server) Orders(ctx context.Context, who keys.Who) ([]OrderInfo, error)
- func (s *Server) Pending(ctx context.Context) (accounts, names int64, err error)
- func (s *Server) ProcessPending(ctx context.Context) error
- func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Server) SetAccountPredecessor(ctx context.Context, id string, policy *predecessor.Policy, who keys.Who) error
- func (s *Server) SetNetwork(dial func(context.Context, string, string) (net.Conn, error), ...)
- func (s *Server) Waiting(ctx context.Context) (int64, error)
Constants ¶
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.
const (
DefaultEABDays = 7
)
EAB key validity bounds in days.
const EABAlgorithm = "hs256"
EABAlgorithm names the MAC keys in the key ring.
const ( // ValidAuthzLifetime: how long a passed challenge counts for new orders // (owner Q6). ValidAuthzLifetime = 7 * 24 * time.Hour )
Limits.
Variables ¶
var DefaultLimits = Limits{OrdersPerAccount: 300, FailedPerName: 5, AccountsPerIP: 10}
DefaultLimits apply without settings.
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 (*Server) ApproveAccount ¶
ApproveAccount lets an account order under the approval level "account".
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 ¶
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) ExpireStale ¶
ExpireStale marks expired orders and authorizations (a job, every few minutes); reads bring a single object up to date on their own.
func (*Server) ProcessPending ¶
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.
Source Files
¶
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). |