codepair

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

README

go-codepair

Go


Pair two devices on a LAN with a short human-typed code and an authenticated key exchange. Package codepair, module github.com/Totative/go-codepair.

Two devices that share a network but no trust can be paired by a person reading a short code from one and typing it into the other. This package is the cryptographic core of that exchange: it mints the code and runs CPace, a password-authenticated key exchange, so the two devices agree on a key only if they hold the same code, and an attacker on the wire gets one guess per run.

Quick start

go get github.com/Totative/go-codepair

A worked example and the contracts: HUMANS.md.

Features

  • Codes: NewCode draws each character uniformly from a caller-chosen alphabet, and Normalize folds a typed code into the form both sides use, so case and separators never matter. Validate enforces a 32-bit entropy floor. NewJoiner and NewHost refuse a code that is not exactly CodeLength characters from Alphabet (ErrCode).
  • Key exchange: Joiner and Host run CPace (draft-irtf-cfrg-cpace-21, ristretto255, SHA-512), bind the protocol label and both ids and display names, and confirm the key in both directions before they return a Pairing.
  • Peer key: the long-term key is HKDF-SHA-512 of the exchange's session key, so it never depends on a guessable value.
  • Rate limiting: NewLimiter returns an error unless its bounds are positive. Limiter is charged once per run, locks a remote out after a set number of failures, and reports when failures in all have reached the point where the caller should drop the code.

Documentation

Doc Audience
HUMANS.md Running and using the package
AGENTS.md Internals, invariants, and why
CONTRIBUTING.md Process — commits, tests, docs
SECURITY.md Vulnerability disclosure
CHANGELOG.md Release notes

License

Apache-2.0, see LICENSE. © 2026 Damon Blais.

Documentation

Overview

Package codepair pair two devices on a LAN with a short human-typed code and an authenticated key exchange.

Index

Constants

View Source
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

View Source
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.

View Source
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.

View Source
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

func Normalize

func Normalize(code string) string

Normalize folds a typed code into the form the handshake uses: upper case, without the dashes and spaces a caller puts between groups. It never fails, so a caller can pass whatever the user entered.

Types

type Config

type Config struct {
	Protocol    string
	PeerKeyInfo string
	CodeLength  int
	Alphabet    string
}

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

func (c Config) NewCode() (string, error)

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

func (c Config) NewHost(code, id, name string) (*Host, error)

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

func (c Config) NewJoiner(code, id, name string) (*Joiner, []byte, error)

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

func (c Config) Validate() error

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

func (h *Host) Accept(joinerMsg []byte) ([]byte, error)

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.

func (*Host) Finish added in v0.3.0

func (h *Host) Finish(confirm []byte) (Pairing, error)

Finish takes the joiner's confirmation. Only a joiner that derived the same key can produce it, so on success the host may store the returned pairing; on any error the Host is spent and nothing else is returned.

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

func (j *Joiner) Finish(hostMsg []byte) (confirm []byte, p Pairing, err error)

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

func NewLimiter(maxFailures, burnFailures int, lockout time.Duration) (*Limiter, error)

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

func (l *Limiter) Charge(remote string, now time.Time) (locked, burned bool)

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

func (l *Limiter) Refund(remote string, now time.Time)

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.

type Pairing added in v0.3.0

type Pairing struct {
	PeerKey  []byte
	PeerID   string
	PeerName string
}

Pairing is what a completed, confirmed run yields. PeerID and PeerName arrive in the peer's message and are authenticated by the confirmation, but this package cannot know which peer the caller meant to pair with: the caller must check them before it stores PeerKey.

Jump to

Keyboard shortcuts

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