Documentation
¶
Overview ¶
Package codepair pair two devices on a LAN with a short human-typed code and an authenticated key exchange.
Index ¶
Constants ¶
const MinCodeBits = 32
MinCodeBits is the least entropy Validate accepts for a code. The code is the only secret and an active attacker gets one guess per run, so the floor keeps a run's success chance, and the Limiter budget times it, small.
Variables ¶
var ErrCode = errors.New("codepair: invalid pairing code")
ErrCode reports a pairing code that is not exactly Config.CodeLength characters from Config.Alphabet after Normalize. Running the handshake on a weaker secret would give an attacker a better guess than Validate allowed.
var ErrConfirmation = errors.New("codepair: key confirmation failed")
ErrConfirmation reports that the peer's key confirmation did not verify: the codes differ, or a message was altered in transit, so the peer did not derive the same key.
var ErrMessage = errors.New("codepair: invalid pairing message")
ErrMessage reports a protocol message that is malformed or that CPace requires aborting on: a wrong length, an invalid or identity group element, or a non-canonical associated-data encoding.
Functions ¶
Types ¶
type Config ¶
Config names the pairing protocol this caller runs. The zero value is not usable: Validate refuses a config that leaves any field out, because an empty Protocol or PeerKeyInfo would derive keys under a shared, guessable label.
func (Config) NewCode ¶
NewCode returns a code of c.CodeLength characters drawn uniformly from c.Alphabet. It is the secret the user types, so a caller may show it in any grouping it likes: Normalize drops the separators again.
func (Config) NewHost ¶ added in v0.3.0
NewHost prepares a run with the code this device showed and its own id and display name.
func (Config) NewJoiner ¶ added in v0.3.0
NewJoiner starts a run with the code the user typed and this device's id and display name. The returned message goes to the host.
func (Config) Validate ¶
Validate reports whether c can mint codes and run a pairing. It refuses a zero field rather than defaulting one, since a default would name a product's protocol inside a library that has none. The alphabet must be distinct printable ASCII that Normalize leaves alone, so a typed code maps to exactly one string, and the code must carry at least MinCodeBits of entropy.
type Host ¶ added in v0.3.0
type Host struct {
// contains filtered or unexported fields
}
Host is the side that shows the code. A Host is not safe for concurrent use and serves one pairing attempt. A caller charges its Limiter for the remote before Accept, because the reply lets whoever sent the joiner message test one guess.
func (*Host) Accept ¶ added in v0.3.0
Accept takes the joiner's message and returns the reply, which carries the host's confirmation. The caller must charge the Limiter for the remote before calling Accept, because the reply is one guess at the code. The run is unconfirmed until Finish verifies the joiner's answer.
type Joiner ¶ added in v0.3.0
type Joiner struct {
// contains filtered or unexported fields
}
Joiner is the side that types the code. It speaks first. A Joiner is not safe for concurrent use and serves one pairing attempt: a failed run needs a new one with a fresh secret.
func (*Joiner) Finish ¶ added in v0.3.0
Finish takes the host's message. It succeeds only when the host's confirmation verifies, which a host that does not know the code cannot produce, and then returns the confirmation to send back and the pairing. On any error the Joiner is spent and nothing else is returned.
type Limiter ¶
type Limiter struct {
// contains filtered or unexported fields
}
Limiter bounds online guessing at the code. A caller charges it once per handshake run, before replying to the joiner's message, because each run lets an active attacker test exactly one guess. Two counts are kept: a per-remote one that locks one computer out after maxFailures, and a global one that reports burnFailures, at which the caller should drop the code.
func NewLimiter ¶
NewLimiter returns a limiter that locks one remote out for lockout once it has failed maxFailures guesses, and reports burned once burnFailures guesses have failed in all. All three bounds must be positive: a zero lockout would never expire, and a zero failure cap would refuse or burn on the first charge without a usable budget.
func (*Limiter) Charge ¶
Charge records one guess from remote and reports whether the guess may be served. locked means remote is inside a lockout; burned means the guesses failed in all have spent burnFailures, and the caller should drop the code. Either way nothing is counted and the guess must be refused. Checking and counting happen under one lock, so concurrent runs cannot jointly pass the limit; the remote is whatever the caller keys on, so a limit per remote holds only as far as an attacker cannot choose it, and the global count is the bound that does not depend on that.
func (*Limiter) Refund ¶
Refund gives back the guess a correct code spent, so a user who mistypes once and then succeeds still has the whole budget. It leaves a lockout in place, since a computer that just exhausted its guesses has not earned them back. A remote with no outstanding charge is left unchanged, so a refund cannot un-burn a budget another guess spent.