Documentation
¶
Overview ¶
Package altcha is a middleware that tells people from bots with a proof-of-work challenge: the browser spends a moment searching for a counter whose PBKDF2 key starts with a prefix signed by the server, and the server checks the answer with two HMACs. Nothing is shown to read and no third party is involved.
Challenges and solutions use the ALTCHA v3 format (https://altcha.org), so the official altcha-widget works as well as the widget this package serves.
Index ¶
Constants ¶
const FieldName = "altcha"
FieldName is the name of the form field the widget writes the solution to.
Variables ¶
var ( // ErrInvalid is returned when a solution is malformed, is not signed by this // server, or does not solve its challenge. ErrInvalid = errors.New("altcha: invalid solution") // ErrExpired is returned when a solution is valid but its challenge expired. ErrExpired = errors.New("altcha: challenge expired") // ErrReplayed is returned when a solution was already accepted once. ErrReplayed = errors.New("altcha: solution already used") )
Functions ¶
func Challenger ¶
Challenger returns a middleware handler that injects altcha.Challenge into the request context, and serves challenges and the widget script under URLPrefix.
Types ¶
type Challenge ¶
type Challenge interface {
// HTML returns the HTML that renders the widget. Put it inside a form; the
// widget writes its solution to the form field named FieldName.
HTML() template.HTML
// Verify verifies a solution submitted by the widget. Each solution is
// accepted at most once. It returns ErrInvalid, ErrExpired, ErrReplayed, or
// an error from the ReplayStore.
Verify(payload string) error
}
Challenge is a proof-of-work service that renders the widget and verifies solutions.
type Options ¶
type Options struct {
// URLPrefix is the URL path prefix for serving challenges and the widget
// scripts. A trailing slash is added when missing. Default is "/.altcha/".
URLPrefix string
// Secret is the key used to sign challenges. It is required, must be at
// least 16 bytes of random data, and must be the same on every server that
// verifies solutions.
Secret []byte
// Cost is the number of PBKDF2 iterations for each counter the browser
// tries. Default is 5000.
Cost int
// MaxCounter is the largest counter a challenge can hide, up to
// math.MaxUint32. The browser tries MaxCounter/2 counters on average, spread
// over its CPU cores. Default is 500.
MaxCounter int
// Expiry is how long a challenge can be solved and submitted. Default is 5
// minutes.
Expiry time.Duration
// Store records accepted solutions so they cannot be used twice. Default is
// an in-memory store, which only works when a single process verifies
// solutions.
Store ReplayStore
}
Options contains options for the altcha.Challenger middleware.