identity

Documentation

Index

• Constants
• Variables
• func DerivePassphraseKey(passphrase string, salt []byte) ([]byte, error)
• func GenerateMasterKey() ([]byte, error)
• func IsKeychainAvailable() bool
• func IsV1Envelope(buf []byte) bool
• func KeychainDelete(account string) error
• func KeychainGet(account string) ([]byte, error)
• func KeychainSet(account string, value []byte) error
• func MarshalEnvelope(h EnvelopeHeader, ciphertextWithTag []byte) []byte
• func WriteFileAtomic(path string, data []byte, mode os.FileMode) error
• type AddressBook
  • func LoadAddressBook(configDir string, src MasterKeySource) (*AddressBook, error)
  • func (ab *AddressBook) Add(name, fingerprint string) error
  • func (ab *AddressBook) ConfigDir() string
  • func (ab *AddressBook) Count() int
  • func (ab *AddressBook) List() []Contact
  • func (ab *AddressBook) Lookup(fingerprint string) *Contact
  • func (ab *AddressBook) Remove(fingerprint string) error
  • func (ab *AddressBook) Save() error
  • func (ab *AddressBook) UpdateLastSeen(fingerprint string)
• type Contact
• type DeviceIdentity
  • func Load(configDir string, src MasterKeySource) (*DeviceIdentity, error)
  • func LoadOrCreate(configDir string, src MasterKeySource) (*DeviceIdentity, error)
  • func (d *DeviceIdentity) Save(configDir string, src MasterKeySource) error
• type EnvelopeHeader
  • func ParseEnvelope(buf []byte) (EnvelopeHeader, []byte, error)
  • func (h EnvelopeHeader) AAD() []byte
• type KeySourceOpts
• type MasterKeySource
  • func NewMasterKeySource(opts KeySourceOpts) (MasterKeySource, error)
• type Tier

Constants

const (
	KDFKeychain   uint8 = 1 // OS keychain (Tier 1a)
	KDFFile       uint8 = 2 // ~/.config/keibidrop/.master.key (Tier 1b)
	KDFPassphrase uint8 = 3 // Argon2id passphrase (Tier 2)
)

KDF identifier constants stored in the envelope header.

const CurrentIdentitySchemaVersion = 1

CurrentIdentitySchemaVersion is the schema_version written by this build.

const PassphraseKDFID = KDFPassphrase

PassphraseKDFID is the kdf_id byte written into the envelope header for passphrase-derived keys.

Variables

var ErrIdentityNeedsPassphrase = errors.New("identity: passphrase required")

var ErrIdentityNewerSchema = errors.New("identity: newer schema version than this build")

Functions

func DerivePassphraseKey

func DerivePassphraseKey(passphrase string, salt []byte) ([]byte, error)

DerivePassphraseKey derives a 32-byte key from passphrase and salt using Argon2id. salt must be at least 16 bytes; passphrase must be non-empty.

func GenerateMasterKey

func GenerateMasterKey() ([]byte, error)

func IsKeychainAvailable

func IsKeychainAvailable() bool

IsKeychainAvailable probes whether the OS keychain is functional by performing a set/get/delete roundtrip with a temporary test value. Returns false on any error (e.g. no D-Bus session, unsupported platform).

func IsV1Envelope

func IsV1Envelope(buf []byte) bool

IsV1Envelope returns true when buf starts with the correct magic bytes and is long enough to contain a complete header + nonce.

func KeychainDelete

func KeychainDelete(account string) error

KeychainDelete removes the entry for account from the OS keychain.

func KeychainGet

func KeychainGet(account string) ([]byte, error)

KeychainGet retrieves a previously stored value by account name and returns the raw bytes (base64-decoded). Returns an error if the account does not exist or the keychain is unavailable.

func KeychainSet

func KeychainSet(account string, value []byte) error

KeychainSet stores value under account in the OS keychain. The bytes are base64-encoded before storage because go-keyring accepts strings only.

func MarshalEnvelope

func MarshalEnvelope(h EnvelopeHeader, ciphertextWithTag []byte) []byte

MarshalEnvelope serialises header + ciphertextWithTag into the wire format:

[magic(4) | format(1) | kdf_id(1) | flags(1) | kdf_param(1) | salt(16) | nonce(12) | ct+tag]

func WriteFileAtomic

func WriteFileAtomic(path string, data []byte, mode os.FileMode) error

WriteFileAtomic writes data to path using a write-then-rename strategy so that readers never see a partial file. The parent directory is created with mode 0750 if it does not exist. On rename failure a best-effort cleanup of the temporary file is attempted.

Types

type AddressBook

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

func LoadAddressBook

func LoadAddressBook(configDir string, src MasterKeySource) (*AddressBook, error)

LoadAddressBook loads the encrypted address book from configDir using src. Returns an empty address book if the file does not exist.

func (*AddressBook) Add

func (ab *AddressBook) Add(name, fingerprint string) error

Add adds a contact. Returns error if fingerprint already exists.

func (*AddressBook) ConfigDir

func (ab *AddressBook) ConfigDir() string

ConfigDir returns the configDir the address book was loaded from.

func (*AddressBook) Count

func (ab *AddressBook) Count() int

Count returns the number of contacts.

func (*AddressBook) List

func (ab *AddressBook) List() []Contact

List returns a copy of all contacts.

func (*AddressBook) Lookup

func (ab *AddressBook) Lookup(fingerprint string) *Contact

Lookup returns a contact by fingerprint, or nil if not found.

func (*AddressBook) Remove

func (ab *AddressBook) Remove(fingerprint string) error

Remove removes a contact by fingerprint.

func (*AddressBook) Save

func (ab *AddressBook) Save() error

Save encrypts and persists the address book to disk using the MasterKeySource that was provided to LoadAddressBook.

func (*AddressBook) UpdateLastSeen

func (ab *AddressBook) UpdateLastSeen(fingerprint string)

UpdateLastSeen updates the last seen time for a contact.

type Contact

type Contact struct {
	SchemaVersion int       `json:"schema_version,omitempty"`
	Name          string    `json:"name"`
	Fingerprint   string    `json:"fingerprint"`
	AddedAt       time.Time `json:"added_at"`
	LastSeen      time.Time `json:"last_seen,omitempty"`
}

type DeviceIdentity

type DeviceIdentity struct {
	Fingerprint string
	Keys        *kbc.OwnKeys
	CreatedAt   time.Time
}

func Load

func Load(configDir string, src MasterKeySource) (*DeviceIdentity, error)

Load reads and decrypts the identity file from configDir using src.

func LoadOrCreate

func LoadOrCreate(configDir string, src MasterKeySource) (*DeviceIdentity, error)

LoadOrCreate loads an existing identity from configDir using src, or creates and persists a new one if none exists.

func (*DeviceIdentity) Save

func (d *DeviceIdentity) Save(configDir string, src MasterKeySource) error

Save encrypts and writes the identity to configDir using src.

type EnvelopeHeader

type EnvelopeHeader struct {
	KDFID    uint8
	Flags    uint8
	KDFParam uint8
	Salt     [envelopeSaltSize]byte
	Nonce    [envelopeNonceSize]byte
}

EnvelopeHeader contains the decoded fields from the first 24 bytes of the envelope. Salt and Nonce are decoded separately; the raw header bytes live in the serialised form produced by MarshalEnvelope.

func ParseEnvelope

func ParseEnvelope(buf []byte) (EnvelopeHeader, []byte, error)

ParseEnvelope decodes an envelope buffer into its header and ciphertext. Returns typed errors for invalid / unsupported envelopes.

func (EnvelopeHeader) AAD

func (h EnvelopeHeader) AAD() []byte

AAD returns the first 24 bytes of the envelope (magic through salt) that must be passed as associated data to EncryptWithAAD / DecryptWithAAD. Tampering with any header byte invalidates the AEAD tag.

type KeySourceOpts

type KeySourceOpts struct {
	ConfigDir          string
	PassphraseProtect  bool
	PassphraseProvider func() (string, error)
	KeychainAvailable  func() bool // nil = real check
	ExternalMaster     []byte      // 32-byte key from mobile bridge (iOS Keychain / Android Keystore)
}

type MasterKeySource

type MasterKeySource interface {
	Master() ([]byte, error)
	Tier() Tier
	KDFID() uint8
}

func NewMasterKeySource

func NewMasterKeySource(opts KeySourceOpts) (MasterKeySource, error)

type Tier

type Tier string

const (
	TierKeychain   Tier = "keychain"
	TierFile       Tier = "file"
	TierPassphrase Tier = "passphrase"
	TierExternal   Tier = "external"
)