security

Documentation

Overview

Package security holds git-lan's long-term identity keys, peer fingerprints, and the trusted-peers ring. The per-connection symmetric encryption lives in internal/e2e; this package is about *who* a peer is, not *how* bytes are encrypted in flight.

Index

• Variables
• func ConstantTimeEqual(a, b []byte) bool
• func FingerprintOf(pub []byte) string
• type Identity
  • func LoadOrCreateIdentity() (*Identity, error)
  • func (id *Identity) Fingerprint() string
  • func (id *Identity) Private() *ecdh.PrivateKey
  • func (id *Identity) PublicKey() []byte
• type TrustEntry
• type TrustRing
  • func LoadTrust() (*TrustRing, error)
  • func (t *TrustRing) Add(hostname, fingerprint string)
  • func (t *TrustRing) FingerprintTrusted(fingerprint string) (string, bool)
  • func (t *TrustRing) Get(hostname string) (TrustEntry, bool)
  • func (t *TrustRing) List() []TrustEntry
  • func (t *TrustRing) Remove(hostname string) bool
  • func (t *TrustRing) Save() error
  • func (t *TrustRing) VerifyHost(hostname, fingerprint string) (trusted bool, err error)

Variables

var ErrFingerprintMismatch = errors.New("peer fingerprint does not match pinned trust entry")

ErrFingerprintMismatch indicates a peer presented an identity that does not match its pinned fingerprint - a possible man-in-the-middle.

Functions

func ConstantTimeEqual

func ConstantTimeEqual(a, b []byte) bool

ConstantTimeEqual compares two byte slices without leaking length-position timing. Length mismatch returns false.

func FingerprintOf

func FingerprintOf(pub []byte) string

FingerprintOf renders a public key as a stable, human-comparable fingerprint: "SHA256:" followed by the unpadded base64url of SHA-256(pubkey).

Types

type Identity

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

Identity is this host's long-term X25519 keypair. Its public half identifies the host to peers; its fingerprint is what users compare and pin. The private half never leaves the machine and is stored 0600.

func LoadOrCreateIdentity

func LoadOrCreateIdentity() (*Identity, error)

LoadOrCreateIdentity loads the persistent identity key, generating and persisting a new one (0600) on first run.

func (*Identity) Fingerprint

func (id *Identity) Fingerprint() string

Fingerprint returns this identity's fingerprint string, e.g. "SHA256:Hk9s...". See FingerprintOf for the format.

func (*Identity) Private

func (id *Identity) Private() *ecdh.PrivateKey

Private returns the underlying private key for use in the authenticated handshake (static-ephemeral Diffie-Hellman).

func (*Identity) PublicKey

func (id *Identity) PublicKey() []byte

PublicKey returns the 32-byte X25519 public key.

type TrustEntry

type TrustEntry struct {
	Hostname    string    `json:"hostname"`
	Fingerprint string    `json:"fingerprint"`
	AddedAt     time.Time `json:"added_at"`
}

TrustEntry pins a hostname to the fingerprint we expect it to present.

type TrustRing

type TrustRing struct {
	Entries map[string]TrustEntry `json:"entries"`
}

TrustRing is the persisted set of trusted peers, keyed by hostname.

func LoadTrust

func LoadTrust() (*TrustRing, error)

LoadTrust reads trusted_peers.json, returning an empty ring if absent.

func (*TrustRing) Add

func (t *TrustRing) Add(hostname, fingerprint string)

Add pins hostname to fingerprint. It overwrites an existing pin (use with care - that is how legitimate key rotation is recorded).

func (*TrustRing) FingerprintTrusted

func (t *TrustRing) FingerprintTrusted(fingerprint string) (string, bool)

FingerprintTrusted reports whether any pinned host uses this fingerprint, returning the hostname when so. Used by the inbound approval path, which sees a peer's identity but not always a reliable hostname.

func (*TrustRing) Get

func (t *TrustRing) Get(hostname string) (TrustEntry, bool)

Get returns the pin for a hostname.

func (*TrustRing) List

func (t *TrustRing) List() []TrustEntry

List returns all pins sorted by hostname.

func (*TrustRing) Remove

func (t *TrustRing) Remove(hostname string) bool

Remove deletes a pin.

func (*TrustRing) Save

func (t *TrustRing) Save() error

Save persists the ring.

func (*TrustRing) VerifyHost

func (t *TrustRing) VerifyHost(hostname, fingerprint string) (trusted bool, err error)

VerifyHost checks a presented fingerprint against any pin for hostname. It distinguishes three cases:

known + match    → trusted, nil error
known + mismatch → ErrFingerprintMismatch (possible MITM)
unknown          → trusted=false, nil error (caller decides: TOFU prompt)