PasswordVault.hpp

1. Overview

The PasswordVault.hpp file is a Encrypted password-vault API in BastionGuard.

Declares master-password lifecycle, metadata persistence, AES-GCM encrypted secret storage, cache synchronization, bulk operations, CSV export, and asynchronous secret retrieval.

The documentation below is generated from the supplied source and covers its API surface, runtime responsibilities, data flow, filesystem or command interactions, concurrency model, and security considerations.

2. Source Inventory

  • Original path: password_manager/PasswordVault.hpp
  • Language: C++
  • Source type: .hpp
  • Line count: 105
  • SHA-256: daa383db1f11123b2d310a63d966bd245a9274ae4fc9e034b2b1182e58c29168

3. Dependencies

The file declares the following compile-time dependencies:

Project

  • PasswordEntry.hpp

C/C++ Runtime

  • string
  • vector
  • functional
  • utility
  • unordered_map
  • mutex
  • atomic

4. Types and Public Contract

The file declares or implements the following principal types:

  • Class: PasswordVault

Declared Public Members

  • PasswordVault();
  • bool initialize();
  • bool isUnlocked() const;
  • bool isFirstRun() const;
  • bool createMasterPassword(const std::string& masterPassword);
  • bool unlock(const std::string& masterPassword);
  • void lock();
  • std::vector<PasswordEntry> loadIndex() const;
  • bool saveIndex(const std::vector<PasswordEntry>& entries) const;
  • bool addEntry(const PasswordEntry& entry, const std::string& secret);
  • bool updateEntry(const PasswordEntry& entry, const std::string& secret);
  • bool deleteEntry(const std::string& id);
  • void deleteAllEntries(std::function<void(bool)> onDone);
  • void addEntriesBulk( const std::vector<std::pair<PasswordEntry, std::string>>& items, std::function<void(int ok, int fail)> onDone);
  • void exportToCSV( std::function<void(std::string csv, std::string err)> onDone) const;
  • void getSecretAsync(const std::string& id, std::function<void(std::string)> callback) const;
  • bool setSecret(const std::string& id, const std::string& secret);
  • bool isCacheReady() const { return cacheReady_.load();
  • } std::string generateId() const;
  • std::string nowIso() const;
  • std::string getIndexPath() const;

5. API and Method Inventory

The following functions or methods are implemented in this file:

  • isCacheReady() – Implements the operation represented by this API.

6. Functional Architecture

Persistent Files

  • Metadata index: ~/.config/BastionGuard/password_manager/index.json.
  • Master-password verifier: ~/.config/BastionGuard/password_manager/master.json.
  • Encrypted secret map: ~/.config/BastionGuard/password_manager/secrets.enc.

Cryptographic Design

  • Uses PBKDF2-HMAC-SHA-256 with a 16-byte random salt.
  • Stores the master-password verifier with 200,000 PBKDF2 iterations.
  • Derives the AES secret-file key with 100,000 PBKDF2 iterations.
  • Encrypts the complete secret map using AES-256-GCM with a 12-byte nonce and 16-byte authentication tag.
  • Stores salt, nonce, ciphertext, and tag as hexadecimal JSON members.

Persistence and Cache

  • Writes JSON through a temporary .tmp file followed by rename().
  • Keeps decrypted secrets in a mutex-protected in-memory cache only while unlocked.
  • Loads the encrypted cache in a detached worker after successful unlock.
  • Clears the master-password string and cache when the vault is locked.

Bulk and Asynchronous Operations

  • Supports bulk insertion with duplicate-ID rejection.
  • Exports decrypted data to CSV on a worker thread.
  • Retrieves secrets asynchronously and waits for cache readiness through a bounded GTK timeout loop.
  • Persists secret snapshots asynchronously after add, update, delete, or set operations.

7. Operational Flow

  1. Initialize the password-manager storage directory and metadata index.
  2. Create or verify the master password and transition the vault into unlocked state.
  3. Load non-secret metadata and asynchronously populate the decrypted secret cache.
  4. Perform add, edit, reveal, import, export, or delete actions.
  5. Persist metadata atomically and rewrite the encrypted secret map.
  6. Clear cached secrets and master-password material when locking.

8. Filesystem and External Command Surface

No hard-coded absolute filesystem path is declared directly in this file.

Commands or Security Primitives Referenced

  • ip
  • sh

9. Concurrency and Lifecycle

  • Uses atomic state for cross-thread progress, lock state, or lifecycle coordination.
  • Protects shared state with a mutex.

10. Security Considerations

  • Password metadata and encrypted secrets are separated, reducing accidental exposure through the index file.
  • Cleartext passwords exist in process memory while the vault is unlocked and during import/export workflows.
  • CSV import and export files are unencrypted and must be handled as sensitive data.
  • Background callbacks must not outlive their owning GTK objects.

11. Implementation Considerations

  • This header defines the public or private class contract; behavior is implemented by the matching .cpp file unless marked inline.

12. Licensing and Branding

The source is distributed under the GNU General Public License version 3.

The source header identifies BastionGuard™ as a trademark and states that the name and branding are not licensed under the GPL.

The software is provided without warranty, including implied warranties of merchantability or fitness for a particular purpose.

Published on:
Last updated on: