codepair

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 12 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, derives the two secrets from it, and proves to each side that the other knows the code, so a device that guesses wrong learns nothing about the key being agreed.

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 hash, so case and separators never matter.
  • Key derivation: Keys stretches the low-entropy code into a proof key with PBKDF2-SHA256 and derives the long-term peer key with HKDF-SHA256 from the shared secret alone, so the stored key cannot be guessed offline.
  • Transcript: Transcript binds the protocol, both public keys, and both ids and display names, so a relay in the middle cannot rename a device and still pass.
  • Proofs: Proof signs the transcript and the shared secret under the peer's role, and Verify compares in constant time.
  • Rate limiting: Limiter counts guesses before they are checked, 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

MIT — see LICENSE. © 2026 Rethunk.Tech, LLC.

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Normalize

func Normalize(code string) string

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

func Proof

func Proof(authKey []byte, role string, transcript, shared []byte) []byte

Proof signs the transcript and the shared secret under authKey with the role the signer plays, so each side sends a different proof and a captured one cannot be replayed as the other.

func Verify

func Verify(want, got []byte) bool

Verify reports whether two proofs match, in time that does not depend on where they first differ.

Types

type Config

type Config struct {
	Protocol    string
	PeerKeyInfo string
	Iterations  int
	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 and a zero Iterations would make the code's stretch free.

func (Config) Keys

func (c Config) Keys(code string, shared, transcript []byte) (authKey, peerKey []byte, err error)

Keys derives the two secrets of one pairing from the typed code and the X25519 shared secret. authKey is the key Proof signs with, stretched from the low-entropy code so that one guess costs c.Iterations of PBKDF2; peerKey is the long-term key HKDF derives from shared alone, so what a caller stores never depends on the code.

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) Transcript

func (c Config) Transcript(a, b []byte, joinerID, joinerName, hostID, hostName string) []byte

Transcript builds the bytes both sides prove over: the protocol, both public keys, then both ids and display names. Because the names are in it, a relay that swaps the name a device is stored under fails the proofs.

func (Config) Validate

func (c Config) Validate() error

Validate reports whether c can mint codes and derive keys. It refuses a zero field rather than defaulting one, since a default would name a product's protocol inside a library that has none.

type Limiter

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

Limiter bounds online guessing at the code. A caller charges it once per guess, before checking the guess, so guesses made side by side cannot outnumber the limit. 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

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.

func (*Limiter) Charge

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

Charge records one guess from remote. It returns burned once the guesses failed in all have reached burnFailures, which is the caller's signal to stop honouring the code; further charges keep returning burned until Refund gives a guess back.

func (*Limiter) Locked

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

Locked reports whether remote is inside a lockout at now.

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.

Jump to

Keyboard shortcuts

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