pairing

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package pairing implements the cryptographic adapters for manually authorized instance pairing. Invitation authorization and atomic replay consumption belong to the application transaction, not this package.

Index

Constants

View Source
const (
	MaxProofAge   = time.Minute
	MaxFutureSkew = 5 * time.Second
	MaxProofBytes = 8192
)
View Source
const (
	PhraseWords = 6
	// Six independent uniform selections from EFF's 7776-word list.
	PhraseEntropyBits = 77.54887502163469
	// Payload limits bound secret processing and encrypted continuation sizes.
	// They are not password-strength requirements.
	MaxPhraseBytes = 4096
	MaxPhraseWords = 128
)
View Source
const (
	SRPVersion      = 4
	SRPBits         = 2048
	SRPElementBytes = SRPBits / 8
)

Variables

View Source
var ErrInvalidExchange = errors.New("pairing: phrase authentication failed")
View Source
var ErrInvalidProof = errors.New("pairing: invalid proof of possession")

Functions

func ContextSalt

func ContextSalt(context Context) ([]byte, error)

ContextSalt supplies a 128-bit salt to the existing v4 password KDF. The library appends "proton" and its bcrypt dependency reads the first 16 salt bytes. Supplying 16 bytes therefore preserves all 128 context-binding bits. This application profile deliberately differs from Proton's usual 10-byte salt convention. It never modifies the PAKE arithmetic or proof construction.

func FinishServer

func FinishServer(enrollment Enrollment, secret, clientEphemeral, clientProof []byte) ([]byte, error)

func GenerateDPoP

func GenerateDPoP(private ed25519.PrivateKey, claims DPoPClaims) (string, error)

func GeneratePhrase

func GeneratePhrase() (string, error)

GeneratePhrase uses the library's CSPRNG dice rolls independently for each word. Repeated words are valid and do not trigger resampling.

func GeneratePhraseWords

func GeneratePhraseWords(count int) (string, error)

GeneratePhraseWords lets the requester choose the generated phrase length.

func NewSigningKey

func NewSigningKey() (ed25519.PrivateKey, error)

func ParsePublicJWK

func ParsePublicJWK(raw []byte) (jose.JSONWebKey, error)

func PublicJWK

func PublicJWK(private ed25519.PrivateKey) (jose.JSONWebKey, error)

func PublicKeyThumbprint

func PublicKeyThumbprint(key jose.JSONWebKey) (string, error)

func ValidatePhrase

func ValidatePhrase(raw string) error

ValidatePhrase accepts user-chosen passwords and phrases without a minimum strength or word count. Case, spacing and Unicode bytes remain significant.

func VerifyServerProof

func VerifyServerProof(expected, actual []byte) error

Types

type Context

type Context struct {
	InviteID            string `json:"invite_id"`
	Origin              string `json:"origin"`
	SPKIPin             string `json:"spki_pin"`
	RequesterThumbprint string `json:"requester_jkt"`
	InviteSalt          []byte `json:"invite_salt"`
}

Context binds the library's password KDF to this invitation and the requester's independently generated signing key. Both parties construct this from their own expected identities. Do not accept requester-controlled serving origin or pin values on the server.

type DPoPClaims

type DPoPClaims struct {
	Method, URL, AccessToken, Nonce, JTI string
	IssuedAt                             time.Time
}

type DPoPExpectation

type DPoPExpectation struct {
	Method, URL, AccessToken, Nonce, Thumbprint string
	Now                                         time.Time
}

type Enrollment

type Enrollment struct {
	Version  int    `json:"version"`
	Salt     []byte `json:"salt"`
	Verifier []byte `json:"verifier"`
}

func EnrollPhrase

func EnrollPhrase(phrase string, context Context) (Enrollment, error)

type Proofs

type Proofs struct {
	ClientEphemeral     []byte `json:"client_ephemeral"`
	ClientProof         []byte `json:"client_proof"`
	ExpectedServerProof []byte `json:"expected_server_proof"`
}

func ClientProof

func ClientProof(phrase string, context Context, serverEphemeral []byte) (Proofs, error)

type ServerChallenge

type ServerChallenge struct {
	Secret    []byte `json:"secret"`
	Ephemeral []byte `json:"ephemeral"`
}

ServerChallenge is serializable. Secret is sensitive ephemeral state and must be sealed in durable storage, never included in a response or logs.

func StartServer

func StartServer(enrollment Enrollment) (ServerChallenge, error)

type VerifiedDPoP

type VerifiedDPoP struct {
	Thumbprint, JTI string
	IssuedAt        time.Time
}

func VerifyDPoP

func VerifyDPoP(raw string, expected DPoPExpectation) (VerifiedDPoP, error)

VerifyDPoP uses go-jose for JWS verification and RFC 7638 thumbprints. The application checks here implement RFC 9449 section 4.3. The caller must reject duplicate HTTP DPoP headers and atomically consume (Thumbprint,JTI) before granting authority; this stateless verifier alone does not prevent replay. https://www.rfc-editor.org/rfc/rfc9449.html#section-4.3

Jump to

Keyboard shortcuts

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