pairing

Documentation

Overview

Package pairing defines the bounded, transcript-bound plumtree-pair-v1 protocol contract. It carries proofs only; private keys and phrases never appear in the wire structures.

Index

• Constants
• Variables
• func ClientProof(secret []byte, t Transcript) ([]byte, error)
• func DeriveKey(secret []byte) ([]byte, error)
• func DeriveVerifier(salt, secret []byte) ([]byte, error)
• func ServerProof(secret []byte, t Transcript) ([]byte, error)
• func VerifyClientProof(secret []byte, t Transcript, received []byte) error
• func VerifyServerProof(secret []byte, t Transcript, received []byte) error
• func WriteFrame(w io.Writer, frame Frame) error
• type ClientHello
• type Complete
• type Frame
  • func ReadFrame(r io.Reader) (Frame, error)
• type Problem
• type Proof
• type Purpose
• type ServerHello
• type Transcript
  • func (t Transcript) Validate() error

Constants

const (
	ProtocolName  = "plumtree-pair-v1"
	MaxFrameSize  = 64 << 10
	MaxSecretSize = 4096

	FrameServerHello byte = 1
	FrameClientHello byte = 2
	FrameServerProof byte = 3
	FrameClientProof byte = 4
	FrameComplete    byte = 5
	FrameProblem     byte = 6
)

Variables

var (
	ErrInvalid       = errors.New("pairing: invalid message")
	ErrProofMismatch = errors.New("pairing: proof mismatch")
	ErrFrameTooLarge = errors.New("pairing: frame too large")
)

Functions

func ClientProof

func ClientProof(secret []byte, t Transcript) ([]byte, error)

func DeriveKey

func DeriveKey(secret []byte) ([]byte, error)

DeriveKey binds a high-entropy out-of-band phrase to this protocol label.

func DeriveVerifier

func DeriveVerifier(salt, secret []byte) ([]byte, error)

DeriveVerifier makes a caller-held phrase usable for transcript proofs without placing the phrase itself in SQLite or on the wire.

func ServerProof

func ServerProof(secret []byte, t Transcript) ([]byte, error)

func VerifyClientProof

func VerifyClientProof(secret []byte, t Transcript, received []byte) error

func VerifyServerProof

func VerifyServerProof(secret []byte, t Transcript, received []byte) error

func WriteFrame

func WriteFrame(w io.Writer, frame Frame) error

WriteFrame uses a four-byte big-endian length including the one-byte type.

Types

type ClientHello

type ClientHello struct {
	Transcript       Transcript `json:"transcript"`
	DeviceName       string     `json:"deviceName,omitempty"`
	RecoverySalt     []byte     `json:"recoverySalt,omitempty"`
	RecoveryVerifier []byte     `json:"recoveryVerifier,omitempty"`
}

type Complete

type Complete struct {
	ServerID     string `json:"serverID"`
	AuthorID     string `json:"authorID"`
	AuthorHandle string `json:"authorHandle"`
	DeviceID     string `json:"deviceID"`
}

type Frame

type Frame struct {
	Type    byte
	Payload []byte
}

func ReadFrame

func ReadFrame(r io.Reader) (Frame, error)

type Problem

type Problem struct {
	Code   string `json:"code"`
	Detail string `json:"detail"`
}

type Proof

type Proof struct {
	Salt        []byte `json:"salt,omitempty"`
	ServerNonce []byte `json:"serverNonce,omitempty"`
	MAC         []byte `json:"mac"`
}

type Purpose

type Purpose string

const (
	PurposeNewAuthor        Purpose = "new-author"
	PurposeAddDevice        Purpose = "add-device"
	PurposeOfflineRecovery  Purpose = "offline-recovery"
	PurposeOperatorRecovery Purpose = "operator-recovery"
)

type ServerHello

type ServerHello struct {
	ServerID           string   `json:"serverID"`
	HostKeyAlgorithm   string   `json:"hostKeyAlgorithm"`
	HostKeyFingerprint string   `json:"hostKeyFingerprint"`
	ProductVersion     string   `json:"productVersion"`
	Protocols          []string `json:"protocols"`
}

type Transcript

type Transcript struct {
	SessionID          string  `json:"sessionID"`
	ServerID           string  `json:"serverID"`
	HostKeyFingerprint string  `json:"hostKeyFingerprint"`
	ClientNonce        []byte  `json:"clientNonce"`
	ServerNonce        []byte  `json:"serverNonce"`
	PublicKey          string  `json:"publicKey"`
	DeviceFingerprint  string  `json:"deviceFingerprint"`
	Purpose            Purpose `json:"purpose"`
	Identifier         string  `json:"identifier"`
}

Transcript binds both SSH endpoints, both fresh nonces, the proposed key, and the purpose. JSON field order is fixed by the struct for stable MACs.

func (Transcript) Validate

func (t Transcript) Validate() error