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
- Variables
- func ContextSalt(context Context) ([]byte, error)
- func FinishServer(enrollment Enrollment, secret, clientEphemeral, clientProof []byte) ([]byte, error)
- func GenerateDPoP(private ed25519.PrivateKey, claims DPoPClaims) (string, error)
- func GeneratePhrase() (string, error)
- func GeneratePhraseWords(count int) (string, error)
- func NewSigningKey() (ed25519.PrivateKey, error)
- func ParsePublicJWK(raw []byte) (jose.JSONWebKey, error)
- func PublicJWK(private ed25519.PrivateKey) (jose.JSONWebKey, error)
- func PublicKeyThumbprint(key jose.JSONWebKey) (string, error)
- func ValidatePhrase(raw string) error
- func VerifyServerProof(expected, actual []byte) error
- type Context
- type DPoPClaims
- type DPoPExpectation
- type Enrollment
- type Proofs
- type ServerChallenge
- type VerifiedDPoP
Constants ¶
const ( MaxProofAge = time.Minute MaxFutureSkew = 5 * time.Second MaxProofBytes = 8192 )
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 )
const ( SRPVersion = 4 SRPBits = 2048 SRPElementBytes = SRPBits / 8 )
Variables ¶
var ErrInvalidExchange = errors.New("pairing: phrase authentication failed")
var ErrInvalidProof = errors.New("pairing: invalid proof of possession")
Functions ¶
func ContextSalt ¶
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 ¶
GeneratePhrase uses the library's CSPRNG dice rolls independently for each word. Repeated words are valid and do not trigger resampling.
func GeneratePhraseWords ¶
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 ¶
ValidatePhrase accepts user-chosen passwords and phrases without a minimum strength or word count. Case, spacing and Unicode bytes remain significant.
func VerifyServerProof ¶
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 DPoPExpectation ¶
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 ServerChallenge ¶
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 ¶
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