keepass::Key Class Reference

Manages database encryption keys for KDB and KDBX formats. More...

#include <key.hh>

Public Types
enum class	SubKeyResolution { kHashSubKeys , kHashSubKeysOnlyIfCompositeKey }
enum class	Kdf { kAes , kArgon2d , kArgon2id }

Public Member Functions
	Key ()=default
	Default constructor. Creates an empty key with no password or key file.
	Key (const Key &other)
	Copy-constructs, allocating wiped copies of all sub keys.
Key &	operator= (const Key &other)
	Copy-assigns, allocating wiped copies of all sub keys.
	Key (const std::string &password)
	Constructs a key with the given password.
	Key (const std::string &password, const std::string &keyfile)
	Constructs a composite key from a password and a key file.
	Key (const std::vector< uint8_t > &transformed_key)
	Constructs a key from a pre-derived transformed master key.
void	SetPassword (const std::string &password)
	Sets the password used to derive the encryption key.
void	SetKeyFile (const std::string &path)
	Loads a key file and derives the key file component from it.
void	SetKeyFile (std::istream &src)
	Loads a key file from an in-memory stream.
void	SetKeyFileData (const uint8_t *data, std::size_t size)
	Loads a key file from an in-memory byte range.
SecureBuffer< 32 >	Transform (const SecureBuffer< 32 > &seed, uint64_t rounds, SubKeyResolution resolution) const
	Derives the composite key using AES-KDF for KDBX 3 databases.
SecureBuffer< 32 >	TransformArgon2 (Kdf kdf, const SecureBytes &salt, uint64_t iterations, uint64_t memory_bytes, uint32_t parallelism, uint32_t argon2_version, SubKeyResolution resolution) const
	Derives the composite key using Argon2 for KDBX 4 databases.

Static Public Member Functions
static Key	FromBytes (const std::string &password, const std::vector< uint8_t > &keyfile)
	Creates a composite key from a password and an in-memory key file.
static Key	FromStream (const std::string &password, std::istream &keyfile)
	Creates a composite key from a password and a key-file stream.

Static Public Attributes
static constexpr std::size_t	kMaxKeyFileBytes = 1024 * 1024
	Maximum size of a key file accepted by the parser.

Detailed Description

Manages database encryption keys for KDB and KDBX formats.

Supports password-based keys, key file-based keys, and composite keys (password + key file combined). Provides key derivation via AES-KDF or Argon2 for KDBX 4 databases.

Member Enumeration Documentation

Kdf

enum class keepass::Key::Kdf

strong

Key derivation functions supported for KDBX 4 databases.

Enumerator
kAes	AES-KDF (repeated AES-ECB, used by KDBX 3).
kArgon2d	Argon2d.
kArgon2id	Argon2id.

SubKeyResolution

enum class keepass::Key::SubKeyResolution

strong

Strategies for how to resolve sub keys before applying the transformation.

Enumerator
kHashSubKeys	All sub keys will be hashed together into a single hash. Single sub keys will be hashed despite not being part of a composite key.
kHashSubKeysOnlyIfCompositeKey	All sub keys will be hashed together into a single hash. If there is only a single sub key, that sub key will be processed as is without any additional hashing.

Constructor & Destructor Documentation

Key() [1/3]

keepass::Key::Key ( const std::string &  password )

explicit

Constructs a key with the given password.

Parameters

password

The password string used to derive the encryption key.

Key() [2/3]

keepass::Key::Key	(	const std::string &	password,
		const std::string &	keyfile
	)

Constructs a composite key from a password and a key file.

Parameters

password	The password string used to derive the password part.
keyfile	Path to the key file used to derive the key file part.

Key() [3/3]

keepass::Key::Key ( const std::vector< uint8_t > &  transformed_key )

explicit

Constructs a key from a pre-derived transformed master key.

The supplied 32-byte key is used directly as the result of any key derivation, bypassing the password and key file processing. This is useful for re-opening databases with an already computed transformed key.

Parameters

transformed_key

The 32-byte pre-derived transformed key.

Member Function Documentation

FromBytes()

static Key keepass::Key::FromBytes ( const std::string &  password, const std::vector< uint8_t > &  keyfile  )

static

Creates a composite key from a password and an in-memory key file.

Parameters

password	Password part of the composite key.
keyfile	Raw key file contents.

Returns

A key carrying both sub keys.

FromStream()

static Key keepass::Key::FromStream ( const std::string &  password, std::istream &  keyfile  )

static

Creates a composite key from a password and a key-file stream.

Parameters

password	Password part of the composite key.
keyfile	Stream containing the key file.

Returns

A key carrying both sub keys.

SetKeyFile() [1/2]

void keepass::Key::SetKeyFile

(

const std::string &

path

)

Loads a key file and derives the key file component from it.

The file may be an XML v1/v2 key file, a 64-character hexadecimal key or 32 raw bytes. Files larger than kMaxKeyFileBytes are rejected.

Parameters

path	Path to the key file on disk.

SetKeyFile() [2/2]

void keepass::Key::SetKeyFile

(

std::istream &

src

)

Loads a key file from an in-memory stream.

The stream is consumed from its current position. At most kMaxKeyFileBytes are read; larger inputs are rejected.

Parameters

src	Stream containing the key file.

SetKeyFileData()

void keepass::Key::SetKeyFileData	(	const uint8_t *	data,
		std::size_t	size
	)

Loads a key file from an in-memory byte range.

Parameters

data	Pointer to the key file contents.
size	Number of bytes in data.

SetPassword()

void keepass::Key::SetPassword

(

const std::string &

password

)

Sets the password used to derive the encryption key.

Parameters

password

The password string used to derive the encryption key.

Transform()

SecureBuffer< 32 > keepass::Key::Transform	(	const SecureBuffer< 32 > &	seed,
		uint64_t	rounds,
		SubKeyResolution	resolution
	)		const

Derives the composite key using AES-KDF for KDBX 3 databases.

Parameters

seed	The key derivation seed (master seed).
rounds	Number of AES-KDF transformation rounds.
resolution	Strategy for resolving sub keys before transformation.

Returns

The derived 32-byte composite key.

TransformArgon2()

SecureBuffer< 32 > keepass::Key::TransformArgon2	(	Kdf	kdf,
		const SecureBytes &	salt,
		uint64_t	iterations,
		uint64_t	memory_bytes,
		uint32_t	parallelism,
		uint32_t	argon2_version,
		SubKeyResolution	resolution
	)		const

Derives the composite key using Argon2 for KDBX 4 databases.

Parameters

kdf	The Argon2 variant to use (Argon2d or Argon2id).
salt	The salt for the key derivation.
iterations	Number of Argon2 iterations (time cost).
memory_bytes	Memory cost in bytes for Argon2.
parallelism	Degree of parallelism for Argon2.
argon2_version	Argon2 algorithm version (0x10 for 1.0, 0x13 for 1.3).
resolution	Strategy for resolving sub keys before transformation.

Returns

The derived 32-byte composite key.

Member Data Documentation

kMaxKeyFileBytes

constexpr std::size_t keepass::Key::kMaxKeyFileBytes = 1024 * 1024

staticconstexpr

Maximum size of a key file accepted by the parser.

Genuine KeePass key files are only a few hundred bytes (32 raw or base64-encoded bytes plus a small XML wrapper). The upper bound keeps a hostile file from making the parser buffer an unbounded amount of data.

---

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

• key.hh