Represents a KeePass (KDB/KDBX) database. More...

#include <database.hh>

Public Types
enum class	Cipher { kAes , kTwofish , kChaCha20 }
	Cipher algorithms supported for encrypting the database payload.

enum class	Kdf { kAes , kArgon2d , kArgon2id }
	Key derivation functions supported by the importer/exporter.

Public Member Functions
std::shared_ptr< Group >	root () const
	Returns the root group of the database.

void	set_root (std::shared_ptr< Group > root)
	Sets the root group of the database.

Cipher	cipher () const
	Returns the cipher used to encrypt the database payload.

void	set_cipher (Cipher cipher)
	Sets the cipher used to encrypt the database payload.

Kdf	kdf () const
	Returns the key derivation function used to derive the master key.

void	set_kdf (Kdf kdf)
	Sets the key derivation function, invalidating any cached transformed key.

const SecureBytes &	master_seed () const
	Returns the master seed.

void	set_master_seed (const std::array< uint8_t, 16 > &master_seed)
	Sets the master seed from a fixed 16-byte array.

void	set_master_seed (const std::vector< uint8_t > &master_seed)
	Sets the master seed from an arbitrary byte vector.

void	set_master_seed (SecureBytes master_seed)
	Sets the master seed from a secure byte buffer.

const std::array< uint8_t, 16 > &	init_vector () const
	Returns the initialization vector.

void	set_init_vector (const std::array< uint8_t, 16 > &init_vector)
	Sets the initialization vector.

const SecureBuffer< 32 > &	transform_seed () const
	Returns the transform seed used for key derivation.

void	set_transform_seed (const std::array< uint8_t, 32 > &transform_seed)
	Sets the transform seed, invalidating any cached transformed key.

void	set_transform_seed (const SecureBuffer< 32 > &transform_seed)

const SecureBuffer< 32 > &	inner_random_stream_key () const
	Returns the inner random stream key.

void	set_inner_random_stream_key (const SecureBuffer< 32 > &key)
	Sets the inner random stream key from a secure buffer.

void	set_inner_random_stream_key (const std::array< uint8_t, 32 > &key)
	Sets the inner random stream key from a fixed 32-byte array.

uint64_t	transform_rounds () const
	Returns the number of AES key-transform rounds.

void	set_transform_rounds (uint64_t transform_rounds)
	Sets the number of AES key-transform rounds, invalidating the cached key.

uint64_t	argon2_memory () const
	Returns the Argon2 memory cost in KiB.

void	set_argon2_memory (uint64_t argon2_memory)
	Sets the Argon2 memory cost in KiB, invalidating the cached key.

uint32_t	argon2_parallelism () const
	Returns the Argon2 parallelism (degree of parallelism).

void	set_argon2_parallelism (uint32_t argon2_parallelism)
	Sets the Argon2 parallelism, invalidating the cached key.

uint32_t	argon2_version () const
	Returns the Argon2 version number.

void	set_argon2_version (uint32_t argon2_version)
	Sets the Argon2 version number, invalidating the cached key.

const SecureBytes &	argon2_salt () const
	Returns the Argon2 salt.

void	set_argon2_salt (const std::vector< uint8_t > &salt)
	Sets the Argon2 salt, invalidating the cached key.

void	set_argon2_salt (SecureBytes salt)

uint64_t	argon2_iterations () const
	Returns the Argon2 iteration count.

void	set_argon2_iterations (uint64_t iterations)
	Sets the Argon2 iteration count, invalidating the cached key.

bool	compress () const
	Returns whether the payload is compressed.

void	set_compress (bool compress)
	Sets whether the payload is compressed.

const SecureBuffer< 32 > &	transformed_key () const
	Returns the transformed master key (if present).

bool	has_transformed_key () const
	Returns whether a transformed key has been computed.

void	set_transformed_key (SecureBuffer< 32 > key)
	Sets the transformed master key and marks it as present.

void	clear_transformed_key ()
	Clears any cached transformed key.

std::shared_ptr< Metadata >	meta () const
	Returns the database metadata.

void	set_meta (std::shared_ptr< Metadata > meta)
	Sets the database metadata.

std::vector< std::shared_ptr< Entry > >	FindEntries (const std::string &query, bool regex=false) const
	Finds entries matching the given query anywhere in the database.

std::vector< std::shared_ptr< Group > >	FindGroups (const std::string &query, bool regex=false) const
	Finds groups matching the given query anywhere in the database.

std::shared_ptr< Entry >	FindEntry (const std::string &title) const
	Finds the first entry with exactly the given title.

std::shared_ptr< Group >	FindGroup (const std::string &name) const
	Finds the first group with exactly the given name.

void	DeleteEntry (const std::array< uint8_t, 16 > &uuid)
	Deletes the entry with the given UUID from the database.

void	DeleteGroup (const std::array< uint8_t, 16 > &uuid)
	Deletes the group with the given UUID and its subtree from the database.

void	DeleteOldHistory ()
	Applies the database history limits to every entry's history.

void	delete_old_history ()
	Alias for DeleteOldHistory using the library's snake_case style.

void	TrashEntry (const std::shared_ptr< Entry > &entry)
	Moves an entry to the recycle bin.

void	TrashGroup (const std::shared_ptr< Group > &group)
	Moves a group to the recycle bin.

void	EmptyRecycleBin ()
	Empties the recycle bin.

bool	IsRecycleBinEnabled () const
	Returns whether a recycle bin is configured.

void	EnableRecycleBin (bool enable=true)
	Enables or disables the recycle bin.

std::string	ToJson (bool include_attachments=false) const

std::string	ToCsv (CsvFormat format=CsvFormat::kCsv) const
	Serializes the database to CSV, one line per entry.

DatabaseDelta	DeltaSince (const Database &previous) const
	Computes the entry-level difference to a previous database snapshot.

size_t	EntryCount () const
	Returns the total number of entries in the database.

size_t	GroupCount () const
	Returns the total number of groups in the database (including the root).

void	Visit (Visitor &visitor) const
	Applies a visitor to every group and entry in the database.

Static Public Member Functions
static std::shared_ptr< Entry >	NewEntry (const std::string &title="")
	Creates a new entry with an optional title.

static std::shared_ptr< Group >	NewGroup (const std::string &name="")
	Creates a new group with an optional name.

static void	AddEntry (const std::shared_ptr< Group > &group, const std::shared_ptr< Entry > &entry)
	Adds an entry to the given group.

static void	AddGroup (const std::shared_ptr< Group > &parent, const std::shared_ptr< Group > &group)
	Adds a group to the given parent group.

static void	MoveEntry (const std::shared_ptr< Entry > &entry, const std::shared_ptr< Group > &new_group)
	Moves an entry to a different group.

static void	MoveGroup (const std::shared_ptr< Group > &group, const std::shared_ptr< Group > &new_parent)
	Moves a group to a different parent group.

Static Public Attributes
static constexpr uint64_t	kMaxTransformRounds = 1U << 28

static constexpr uint64_t	kMaxArgon2MemoryKiB = 1U << 20

static constexpr uint64_t	kMaxArgon2Iterations = 1U << 20

Detailed Description

Represents a KeePass (KDB/KDBX) database.

A Database holds the root Group of entries and groups, the chosen cipher and key derivation function, and the cryptographic material (master seed, init vector, transform seed, ...) needed to encrypt and decrypt the payload. Metadata such as the database name and custom icons is stored separately via meta().

Member Function Documentation

◆ DeleteOldHistory()

void keepass::Database::DeleteOldHistory ( )

Applies the database history limits to every entry's history.

The limits are read from Metadata::history_max_items and Metadata::history_max_size; a negative value means unlimited, as in the KeePass format. The newest history versions are retained.

◆ DeltaSince()

DatabaseDelta keepass::Database::DeltaSince ( const Database & previous ) const

Computes the entry-level difference to a previous database snapshot.

Entries are matched by UUID. An entry is modified when its canonical Entry::ToJson() representation or its group path changed. Use the result to write a small incremental export for backup tools; groups themselves are represented by the entry paths.

◆ FindEntries()

std::vector< std::shared_ptr< Entry > > keepass::Database::FindEntries	(	const std::string &	query,
		bool	regex = `false`
	)		const

Finds entries matching the given query anywhere in the database.

Parameters

query	The title to search for.
regex	Whether the query is a regular expression.

Returns: The matching entries.

◆ FindEntry()

std::shared_ptr< Entry > keepass::Database::FindEntry ( const std::string & title ) const

Finds the first entry with exactly the given title.

Parameters

title The exact title of the entry to find.

Returns: The entry, or nullptr if no entry matches.

◆ FindGroup()

std::shared_ptr< Group > keepass::Database::FindGroup ( const std::string & name ) const

Finds the first group with exactly the given name.

Parameters

name	The exact name of the group to find.

Returns: The group, or nullptr if no group matches.

◆ FindGroups()

std::vector< std::shared_ptr< Group > > keepass::Database::FindGroups	(	const std::string &	query,
		bool	regex = `false`
	)		const

Finds groups matching the given query anywhere in the database.

Parameters

query	The name to search for.
regex	Whether the query is a regular expression.

Returns: The matching groups.

◆ set_argon2_salt()

void keepass::Database::set_argon2_salt ( SecureBytes salt )

inline

Sets the Argon2 salt from a secure byte buffer, invalidating the cached key.

◆ set_inner_random_stream_key() [1/2]

void keepass::Database::set_inner_random_stream_key ( const SecureBuffer< 32 > & key )

inline

Sets the inner random stream key from a secure buffer.

Parameters

key	The low-level copy of the key to store.

◆ set_inner_random_stream_key() [2/2]

void keepass::Database::set_inner_random_stream_key ( const std::array< uint8_t, 32 > & key )

inline

Sets the inner random stream key from a fixed 32-byte array.

Parameters

key	The 32-byte inner random stream key.

◆ set_transform_seed()

void keepass::Database::set_transform_seed ( const SecureBuffer< 32 > & transform_seed )

inline

Sets the transform seed from a secure buffer, invalidating the cached transformed key.

◆ ToCsv()

std::string keepass::Database::ToCsv ( CsvFormat format = CsvFormat::kCsv ) const

Serializes the database to CSV, one line per entry.

The output starts with the header line "Group,Title,Username,Password,Url,Notes". The group column holds the '/'-joined path of the group an entry lives in (relative to and including the root group). Fields containing a comma, a double quote or a newline are quoted per RFC 4180 (embedded quotes are doubled). Meta entries are skipped.

kCsv omits passwords, kCsvWithPasswords includes them, kCsvWithCustomFields appends a CustomFields column (key=value; ...) and kCsvKeePass2 emits the KeePass 2.x CSV layout (Account,Login Name,Password,Web Site,Comments, passwords included).

Parameters

format Output schema and password handling.

Returns: The CSV data including the header line.

◆ ToJson()

std::string keepass::Database::ToJson ( bool include_attachments = false ) const

Serializes the whole database to a JSON string.

Parameters

include_attachments Include attachment payloads as base64.

Member Data Documentation

◆ kMaxArgon2MemoryKiB

constexpr uint64_t keepass::Database::kMaxArgon2MemoryKiB = 1U << 20

staticconstexpr

Upper bounds on Argon2 key-derivation parameters accepted from untrusted input (memory is in KiB, matching the format). Argon2 costs O(iterations * memory), so unbounded values would allow CPU-burn and memory-exhaustion attacks from a malformed file.

◆ kMaxTransformRounds

constexpr uint64_t keepass::Database::kMaxTransformRounds = 1U << 28

staticconstexpr

Upper bound on the AES-KDF transform round count accepted from untrusted input. The key transform costs O(rounds), so an unbounded value lets a malformed file stall the importer (CPU-burn DoS). Legitimate databases stay far below this limit.

The documentation for this class was generated from the following file:

database.hh

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ DeleteOldHistory()

◆ DeltaSince()

◆ FindEntries()

◆ FindEntry()

◆ FindGroup()

◆ FindGroups()

◆ set_argon2_salt()

◆ set_inner_random_stream_key() [1/2]

◆ set_inner_random_stream_key() [2/2]

◆ set_transform_seed()

◆ ToCsv()

◆ ToJson()

Member Data Documentation

◆ kMaxArgon2MemoryKiB

◆ kMaxTransformRounds