File::KDBX(3pm)

📦

version 0.906 · 4 versions

0.906 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.906 · fedora 43
0.906 · fedora 44
0.906 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

✨ File::KDBX ✨

okay so you found the manual page for File::KDBX(3pm), which lives in the User Contributed Perl Documentation section, and bestie, you're in for a treat 💖

🎀 NAME 🎀

File::KDBX — Encrypted database to store secret text and files 🗝️

🌸 VERSION 🌸

version 0.906

🦋 SYNOPSIS 🦋

use File::KDBX;

# Create a new database from scratch
my $kdbx = File::KDBX->new;

# Add some objects to the database
my $group = $kdbx->add_group(
    name => 'Passwords',
);
my $entry = $group->add_entry(
    title    => 'My Bank',
    username => 'mreynolds',
    password => 's3cr3t',
);

# Save the database to the filesystem
$kdbx->dump_file('passwords.kdbx', 'masterpw changeme');

# Load the database from the filesystem into a new database instance
my $kdbx2 = File::KDBX->load_file('passwords.kdbx', 'masterpw changeme');

# Iterate over database entries, print entry titles
$kdbx2->entries->each(sub($entry, @) {
    say 'Entry: ', $entry->title;
});

See "RECIPES" for more examples 👀

💜 DESCRIPTION 💜

File::KDBX literally gives you everything you need to work with KDBX databases. And what even is a KDBX database? So glad you asked, bestie — it's a hierarchical object database, and people use it to store secret information securely. It was developed for the KeePass password safe. Wanna know more about the format itself? Go read "Introduction to KDBX". 🫶

This module lets you query entries, create new entries, delete entries, modify entries and more. The distribution also includes various parsers and generators for serializing and persisting databases. It's giving range. 💅

The design of this software was influenced by the KeePassXC implementation of KeePass (https://github.com/keepassxreboot/keepassxc) as well as the File::KeePass module. So File::KeePass is an alternative module that works well in most cases but has a small backlog of bugs and security issues and also does not work with newer KDBX version 4 files 😬. If you're coming here from the File::KeePass world, you might be interested in File::KeePass::KDBX that is a drop-in replacement for File::KeePass that uses File::KDBX for storage. Glow-up tbh ✨

This software is a pre-1.0 release. The interface should be considered pretty stable, but there might be minor changes up until a 1.0 release. Breaking changes will be noted in the Changes file. 👑

🍓 Features 🍓

☑ Read and write KDBX version 3 - version 4.1
☑ Read and write KDB files (requires File::KeePass)
☑ Unicode character strings
☑ "Simple Expression" Searching
☑ Placeholders and field references
☑ One-time passwords
☑ Very secure
☑ "Memory Protection"
☑ Challenge-response key components, like YubiKey
☑ Variety of key file types: binary, hexed, hashed, XML v1 and v2
☑ Pluggable registration of different kinds of ciphers and key derivation functions
☑ Built-in database maintenance functions
☑ Pretty fast, with XS optimizations available
☒ Database synchronization / merging (not yet)

🧚 Introduction to KDBX 🧚

A KDBX database consists of a tree of groups and entries, with a single root group. Entries can contain zero or more key-value pairs of strings and zero or more binaries (i.e. octet strings). Groups, entries, strings and binaries: that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is associated with each entry, group and the database as a whole.

You can think of a KDBX database kind of like a file system, where groups are directories, entries are files, and strings and binaries make up a file's contents. fyi that analogy ates 🌈

Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e. not over a network). The primary focus of this type of database is data security. It is ideal for storing relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as have the correct master key. Even if the database file were to be "leaked" to the public Internet, it should be virtually impossible to crack with a strong key. The KDBX format is most often used by password managers to store passwords so that users can know a single strong password and not have to reuse passwords across different websites. See "SECURITY" for an overview of security considerations. 🔐

👑 ATTRIBUTES 👑

`sig1`

`sig2`

`version`

`headers`

`inner_headers`

`meta`

`binaries`

no notes were given for these seven in the original, so no spoilers here — they're just vibes and raw structure fields iykyk 🤐

`deleted_objects`

Hash of UUIDs for objects that have been deleted. This includes groups, entries and even custom icons. 🗑️

`raw`

Bytes contained within the encrypted layer of a KDBX file. This is only set when using File::KDBX::Loader::Raw.

`comment`

A text string associated with the database stored unencrypted in the file header. Often unset.

`cipher_id`

The UUID of a cipher used to encrypt the database when stored as a file.

See File::KDBX::Cipher.

`compression_flags`

Configuration for whether or not and how the database gets compressed. See :compression in File::KDBX::Constants.

`master_seed`

The master seed is a string of 32 random bytes that is used as salt in hashing the master key when loading and saving the database. If a challenge-response key is used in the master key, the master seed is also the challenge.

The master seed should be changed each time the database is saved to file. 🔄

`transform_seed`

The transform seed is a string of 32 random bytes that is used in the key derivation function, either as the salt or the key (depending on the algorithm).

The transform seed should be changed each time the database is saved to file. 🔄

`transform_rounds`

The number of rounds or iterations used in the key derivation function. Increasing this number makes loading and saving the database slower in order to make dictionary and brute force attacks more costly. 💀

`encryption_iv`

The initialization vector used by the cipher.

The encryption IV should be changed each time the database is saved to file. 🔄

`inner_random_stream_key`

The encryption key (possibly including the IV, depending on the cipher) used to encrypt the protected strings within the database.

`stream_start_bytes`

A string of 32 random bytes written in the header and encrypted in the body. If the bytes do not match when loading a file then the wrong master key was used or the file is corrupt. Only KDBX 2 and KDBX 3 files use this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of the header and entire file body.

`inner_random_stream_id`

A number indicating the cipher algorithm used to encrypt the protected strings within the database, usually Salsa20 or ChaCha20. See :random_stream in File::KDBX::Constants.

`kdf_parameters`

A hash/dict of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to configure the KDF, superceding transform_seed and transform_rounds.

`generator`

The name of the software used to generate the KDBX file.

`header_hash`

The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)

`database_name`

Name of the database.

`database_name_changed`

Timestamp indicating when the database name was last changed.

`database_description`

Description of the database

`database_description_changed`

Timestamp indicating when the database description was last changed.

`default_username`

When a new entry is created, the UserName string will be populated with this value.

`default_username_changed`

Timestamp indicating when the default username was last changed.

`color`

A color associated with the database (in the form "#ffffff" where "f" is a hexidecimal digit). Some agents use this to help users visually distinguish between different databases. 🎨

`master_key_changed`

Timestamp indicating when the master key was last changed.

`master_key_change_rec`

Number of days until the agent should prompt to recommend changing the master key.

`master_key_change_force`

Number of days until the agent should prompt to force changing the master key.

Note: This is purely advisory. It is up to the individual agent software to actually enforce it. File::KDBX does NOT enforce it. 🚨

`custom_icons`

Array of custom icons that can be associated with groups and entries.

This list can be managed with the methods "add_custom_icon" and "remove_custom_icon".

`recycle_bin_enabled`

Boolean indicating whether removed groups and entries should go to a recycle bin or be immediately deleted. ♻️

`recycle_bin_uuid`

The UUID of a group used to store thrown-away groups and entries.

`recycle_bin_changed`

Timestamp indicating when the recycle bin group was last changed.

`entry_templates_group`

The UUID of a group containing template entries used when creating new entries.

`entry_templates_group_changed`

Timestamp indicating when the entry templates group was last changed.

`last_selected_group`

The UUID of the previously-selected group.

`last_top_visible_group`

The UUID of the group visible at the top of the list.

`history_max_items`

The maximum number of historical entries that should be kept for each entry. Default is 10.

`history_max_size`

The maximum total size (in bytes) that each individual entry's history is allowed to grow. Default is 6 MiB.

`maintenance_history_days`

The maximum age (in days) historical entries should be kept. Default it 365.

`settings_changed`

Timestamp indicating when the database settings were last updated.

`protect_title`

Alias of the "memory_protection" setting for the Title string.

`protect_username`

Alias of the "memory_protection" setting for the UserName string.

`protect_password`

Alias of the "memory_protection" setting for the Password string.

`protect_url`

Alias of the "memory_protection" setting for the URL string.

`protect_notes`

Alias of the "memory_protection" setting for the Notes string.

💅 METHODS 💅

`new`

$kdbx = File::KDBX->new(%attributes);
$kdbx = File::KDBX->new($kdbx); # copy constructor

Construct a new File::KDBX. ✨

`init`

$kdbx = $kdbx->init(%attributes);

Initialize a File::KDBX with a set of attributes. Returns itself to allow method chaining. 🔗

This is called by "new".

`reset`

$kdbx = $kdbx->reset;

Set a File::KDBX to an empty state, ready to load a KDBX file or build a new one. Returns itself to allow method chaining. 🔗

`clone`

$kdbx_copy = $kdbx->clone;
$kdbx_copy = File::KDBX->new($kdbx);

Clone a File::KDBX. The clone will be an exact copy and completely independent of the original. 🪞

`load`

`load_string`

`load_file`

`load_handle`

$kdbx = KDBX::File->load(\$string, $key);
$kdbx = KDBX::File->load(*IO, $key);
$kdbx = KDBX::File->load($filepath, $key);
$kdbx->load(...);           # also instance method

$kdbx = File::KDBX->load_string($string, $key);
$kdbx = File::KDBX->load_string(\$string, $key);
$kdbx->load_string(...);    # also instance method

$kdbx = File::KDBX->load_file($filepath, $key);
$kdbx->load_file(...);      # also instance method

$kdbx = File::KDBX->load_handle($fh, $key);
$kdbx = File::KDBX->load_handle(*IO, $key);
$kdbx->load_handle(...);    # also instance method

Okay so like — read a KDBX file in from a string buffer, an IO handle, or a file on a filesystem. That's the whole vibe. 🫶

And who's actually doing the work? Not this method bestie, it's File::KDBX::Loader doing the heavy lifting. She's the icon, this is just the face. 💅

💾 `dump`, `dump_string`, `dump_file`, `dump_handle` 💾

$kdbx->dump(\$string, $key);
$kdbx->dump(*IO, $key);
$kdbx->dump($filepath, $key);

$kdbx->dump_string(\$string, $key);
\$string = $kdbx->dump_string($key);

$kdbx->dump_file($filepath, $key);

$kdbx->dump_handle($fh, $key);
$kdbx->dump_handle(*IO, $key);

Write a KDBX file out to a string buffer, an IO handle, or a file on a filesystem. Same three destinations, but the other direction. 🦋

And the one carrying the team this time? File::KDBX::Dumper. She does the heavy lifting. Respect her. ✨

🎀 `user_agent_string` 🎀

$string = $kdbx->user_agent_string;

Hands you back a text string that identifies the database client software. Like a lil name tag for whoever's touching the file. 😌

🔐 `memory_protection` 🔐

\%settings = $kdbx->memory_protection
$kdbx->memory_protection(\%settings);

$bool = $kdbx->memory_protection($string_key);
$kdbx->memory_protection($string_key => $bool);

Get or set the memory protection settings, bestie. This configures — globally, like for the whole database — whether the standard strings get memory-protected, and which ones. The default setting is to memory-protect only Password strings. 🔥

And here's the tea: memory protection can be toggled individually for each entry string, and those individual settings take precedence over these global settings. So the lil one-on-one always wins. periodt. 💅

📼 `minimum_version` 📼

$version = $kdbx->minimum_version;

Figure out the minimum file version you'd need to save this database losslessly. Using certain database features might push this value up. For example, setting the KDF to Argon2 will increase the minimum version to at least KDBX_VERSION_4_0 (i.e. 0x00040000) because Argon2 was introduced with KDBX4. So like... she's got standards, and the standards go up when you use fancy features. 👑

This method never returns less than KDBX_VERSION_3_1 (i.e. 0x00030001). That file version is so ubiquitous and well-supported that there are seldom reasons to dump in a lesser format nowadays. It's giving "why would you even". 💀

WARNING: ⚠️ If you dump a database with a minimum version higher than the current version, the dumper will typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order to avoid data loss, but lower versions have the benefit of being compatible with more software. It is possible to prevent auto-upgrades by explicitly telling the dumper which version to use, but you do run the risk of data loss. A database will never be automatically downgraded. No cap. 🫣

🌳 `root` 🌳

$group = $kdbx->root;
$kdbx->root($group);

Get or set a database's root group. And honestly? You don't necessarily need to explicitly create or set a root group, because it autovivifies when you add entries and groups to the database. She just shows up. main character energy fr. ✨

Every database has only a single root group at a time. Some old KDB files might have multiple root groups. When reading such files, a single implicit root group is created to contain the actual root groups. When writing to such a format, if the root group looks like it was implicitly created then it won't be written and the resulting file might have multiple root groups, as it was before loading. This allows working with older files without changing their written internal structure while still adhering to modern semantics while the database is opened. It's giving respecting her elders while still being a modern girl. 🌈

The root group of a KDBX database contains all of the database's entries and other groups. So heads up: if you replace the root group, you are essentially replacing the entire database contents with something else. Girl. That's the whole plot. 😭

🧬 `trace_lineage` 🧬

\@lineage = $kdbx->trace_lineage($group);
\@lineage = $kdbx->trace_lineage($group, $base_group);
\@lineage = $kdbx->trace_lineage($entry);
\@lineage = $kdbx->trace_lineage($entry, $base_group);

Get the direct line of ancestors from $base_group (default: the root group) to a group or entry. It's a family tree moment. 🌸

The lineage includes the base group but not the target group or entry. Returns undef if the target is not in the database structure — so if she's not in the family, you get nothing. 💀

🗑️ `recycle_bin` 🗑️

$group = $kdbx->recycle_bin;
$kdbx->recycle_bin($group);

Get or set the recycle bin group. Returns undef if there is no recycle bin and recycle_bin_enabled is false, otherwise the current recycle bin or an autovivified recycle bin group is returned. So she either exists, or she materializes. 🧚

📋 `entry_templates` 📋

$group = $kdbx->entry_templates;
$kdbx->entry_templates($group);

Get or set the entry templates group. May return undef if unset. No set, no group, simple as. 🙈

⭐ `last_selected` ⭐

$group = $kdbx->last_selected;
$kdbx->last_selected($group);

Get or set the last selected group. May return undef if unset. It's literally just remembering where you were. Obsessed. 💜

👀 `last_top_visible` 👀

$group = $kdbx->last_top_visible;
$kdbx->last_top_visible($group);

Get or set the last top visible group. May return undef if unset. Same deal, different scroll position bestie. 🦋

➕ `add_group` ➕

$kdbx->add_group($group);
$kdbx->add_group(%group_attributes, %options);

Add a group to a database. This is equivalent to identifying a parent group and calling add_group in File::KDBX::Group on the parent group, forwarding the arguments. So like, the group does the actual work, this is just the handoff. 🤝

Available options:

"group" — Group object or group UUID to add the group to (default: root group)

🌲 `groups` 🌲

\&iterator = $kdbx->groups(%options);
\&iterator = $kdbx->groups($base_group, %options);

Get an File::KDBX::Iterator over groups within a database. Ooh, an iterator, she's fancy. 🎀

Options:

"base" — Only include groups within a base group (same as $base_group) (default: "root")
"inclusive" — Include the base group in the results (default: true)
"algorithm" — Search algorithm, one of "ids", "bfs" or "dfs" (default: "ids")

➕ `add_entry` ➕

$kdbx->add_entry($entry, %options);
$kdbx->add_entry(%entry_attributes, %options);

Add an entry to a database. This is equivalent to identifying a parent group and calling add_entry in File::KDBX::Group on the parent group, forwarding the arguments. Same energy as add_group, but for entries. 💫

Available options:

"group" — Group object or group UUID to add the entry to (default: root group)

📚 `entries` 📚

\&iterator = $kdbx->entries(%options);
\&iterator = $kdbx->entries($base_group, %options);

Get an File::KDBX::Iterator over entries within a database. Supports the same options as groups, plus some new ones:

"auto_type" — Only include entries with auto-type enabled (default: false, include all)
"searching" — Only include entries within groups with searching enabled (default: false, include all)
"history" — Also include historical entries (default: false, include only current entries)

🧸 `objects` 🧸

\&iterator = $kdbx->objects(%options);
\&iterator = $kdbx->objects($base_group, %options);

Get an File::KDBX::Iterator over objects within a database. Groups and entries are considered objects, so this is essentially a combination of groups and entries. This won't often be useful, but it can be convenient for maintenance tasks. She's not the star of the show, she's the stage crew. 👑

This method takes the same options as groups and entries.

🎨 `custom_icon` 🎨

\%icon = $kdbx->custom_icon($uuid);
$kdbx->custom_icon($uuid => \%icon);
$kdbx->custom_icon(%icon);
$kdbx->custom_icon(uuid => $value, %icon);

Get or set custom icons. The aesthetics department. 💅

🖼️ `custom_icon_data` 🖼️

$image_data = $kdbx->custom_icon_data($uuid);

Get a custom icon image data. Just the pixels, ma'am. ✨

🌟 `add_custom_icon` 🌟

$uuid = $kdbx->add_custom_icon($image_data, %attributes);
$uuid = $kdbx->add_custom_icon(%attributes);

Add a custom icon and get its UUID. If not provided, a random UUID will be generated — surprise, you get a UUID anyway, she's generous like that. 🎁

Possible attributes:

"uuid" — Icon UUID (default: autogenerated)
"data" — Image data (same as $image_data)
"name" — Name of the icon (text, KDBX4.1+)
"last_modification_time" — Just what it says (datetime, KDBX4.1+)

💔 `remove_custom_icon` 💔

$kdbx->remove_custom_icon($uuid);

Remove a custom icon. Not me deleting her. 😭

🗂️ `custom_data` 🗂️

\%all_data = $kdbx->custom_data;
$kdbx->custom_data(\%all_data);

\%data = $kdbx->custom_data($key);
$kdbx->custom_data($key => \%data);
$kdbx->custom_data(%data);
$kdbx->custom_data(key => $value, %data);

Get and set custom data. Custom data is metadata associated with a database. Little notes she keeps about herself. 🫶

Each data item can have a few attributes associated with it:

"key" — A unique text string identifier used to look up the data item (required)
"value" — A text string value (required)
"last_modification_time" (optional, KDBX4.1+)

🔎 `custom_data_value` 🔎

$value = $kdbx->custom_data_value($key);

Exactly the same as custom_data except returns just the custom data's value rather than a structure of attributes. This is a shortcut for:

my $data = $kdbx->custom_data($key);
my $value = defined $data ? $data->{value} : undef;

She does the digging so you don't have to. 💅

📢 `public_custom_data` 📢

\%all_data = $kdbx->public_custom_data;
$kdbx->public_custom_data(\%all_data);

$value = $kdbx->public_custom_data($key);
$kdbx->public_custom_data($key => $value);

Get and set public custom data. Public custom data is similar to custom data but different in some important ways:

can store strings, booleans and up to 64-bit integer values (custom data can only store text values)
is NOT encrypted within a KDBX file (hence the "public" part of the name)
is a plain hash/dict of key-value pairs with no other associated fields (like modification times)

So yeah, her whole thing is being out in the open. That's the bit. 🙈

➕ `add_deleted_object` ➕

$kdbx->add_deleted_object($uuid);

Add a UUID to the deleted objects list. This list is used to support automatic database merging.

You typically do not need to call this yourself because the list will be populated automatically as objects are removed. She handles it, bestie. 💜

➖ `remove_deleted_object` ➖

$kdbx->remove_deleted_object($uuid);

Remove a UUID from the deleted objects list. This list is used to support automatic database merging.

You typically do not need to call this yourself because the list will be maintained automatically as objects are added. Again — she's got it. 🫶

🧹 `clear_deleted_objects` 🧹

Remove all UUIDs from the deleted objects list. This list is used to support automatic database merging, but if you don't need merging then you can clear deleted objects to reduce the database file size. Marie Kondo moment. If it doesn't spark merging, toss it. ✨

🔗 `resolve_reference` 🔗

$string = $kdbx->resolve_reference($reference);
$string = $kdbx->resolve_reference($wanted, $search_in, $expression);

Resolve a field reference. The full lore lives at https://keepass.info/help/base/fieldrefs.html, but here's the tea: a field reference is a little string placeholder, and you can use one to point straight at a standard field inside an entry. Field references get resolved automatically whenever entry strings are expanded (that's the whole "replacing placeholders" thing 💫), but you can also call this method yourself when you want to resolve an on-the-fly reference that isn't part of any actual string living in the database.

If the reference doesn't resolve to any field at all, you get undef back, sorry bestie 😭. If it resolves to multiple fields, only the first one gets returned (same order as iterated by entries). To dodge the ambiguity entirely, you can point at one specific entry by its UUID.

The syntax of a reference is literally: {REF:<WantedField>@<SearchIn>:<Text>}. Text is a "Simple Expression". WantedField and SearchIn are both single character codes representing a field:

T — Title
U — UserName
P — Password
A — URL
N — Notes
I — UUID
O — Other custom strings

Since O doesn't represent any specific field, it cannot be used as the WantedField. Not up for debate 💅

Examples:

To get the value of the UserName string of the first entry with My Bank in the title:

my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
# OR the {REF:...} wrapper is optional
my $username = $kdbx->resolve_reference('U@T:"My Bank"');
# OR separate the arguments
my $username = $kdbx->resolve_reference(U => T => '"My Bank"');

Notice how the text is a "Simple Expression", so search terms with spaces must be wrapped in double quotes. Periodt.

To get the Password string of a specific entry (identified by its UUID):

my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');

lock

$kdbx->lock;

Encrypt every protected string and binary in a database 🔒. The encrypted data gets stashed in a File::KDBX::Safe associated with the database, and the actual values get swapped out for undef to signal their protected state. Returns itself so you can chain methods like the icon you are.

You can totally call lock on an already-locked database too — it memory-protects any unprotected strings and binaries that got added since the last time the database was locked. Nothing slips through, no cap.

unlock

$kdbx->unlock;

Decrypt all the protected strings and binaries in a database, replacing those undef value placeholders with their actual, unprotected values 🔓. Returns itself, so chain away. Bestie, don't forget this one, or your passwords will just look like sad little undefs.

unlock_scoped

$guard = $kdbx->unlock_scoped;

Unlock a database temporarily, then relock it when the guard is released (usually at the end of a scope). Returns undef if the database is already unlocked. Peak laziness-elegance combo, honestly ✨

See lock and unlock.

Example:

{
    my $guard = $kdbx->unlock_scoped;
    ...;
}
# $kdbx is now memory-locked

peek

$string = $kdbx->peek(\%string);
$string = $kdbx->peek(\%binary);

Peek at the value of one protected string or binary without unlocking the whole entire database 🙈. The argument can be a string or binary hashref as returned by string in File::KDBX::Entry or binary in File::KDBX::Entry. Just a little look. A lil glance. No big reveal.

is_locked

$bool = $kdbx->is_locked;

Get whether a database's contents are in a locked (i.e. memory-protected) state. If this comes back true, then some or all of the protected strings and binaries in the database are unavailable — like, literally have undef values — until unlock gets called. 🫣

remove_empty_groups

$kdbx->remove_empty_groups;

Remove groups that have no subgroups and no entries. Clean sweep 🧹

remove_unused_icons

$kdbx->remove_unused_icons;

Remove icons that aren't associated with any entry or group in the database. If nothing's using it, it's not staying.

remove_duplicate_icons

$kdbx->remove_duplicate_icons;

Remove duplicate icons as determined by hashing the icon data. Two icons, same hash, one survivor 💀

prune_history

$kdbx->prune_history(%options);

Remove just as many older historical entries as necessary to get under certain limits. Only as many as necessary, bestie — it's not out here being extra.

max_items — Maximum number of historical entries to keep (default: value of history_max_items, no limit: -1)
max_size — Maximum total size (in bytes) of historical entries to keep (default: value of history_max_size, no limit: -1)
max_age — Maximum age (in days) of historical entries to keep (default: value of maintenance_history_days, no limit: -1)

randomize_seeds

$kdbx->randomize_seeds;

Set various keys, seeds and IVs to random values 🌈. These are the values the cryptographic functions lean on to secure the database when it's dumped. The attributes that'll get randomized are:

encryption_iv
inner_random_stream_key
master_seed
stream_start_bytes
transform_seed

Randomizing these values has no effect on a loaded database. They're only used when a database is dumped. And you normally don't need to call this method explicitly at all, because the dumper does it for you by default. Iconic of the dumper, honestly.

key

$key = $kdbx->key;
$key = $kdbx->key($key);
$key = $kdbx->key($primitive);

Get or set a File::KDBX::Key. This is the master key (like a password, or a key file that can decrypt a database). You can also hand it a primitive castable to a Key — see new in File::KDBX::Key for an explanation of what that primitive can be.

You generally don't need to call this directly because you can just provide the key straight to the loader or dumper when loading or dumping a KDBX file. Shortcut behavior, we love her.

composite_key

$key = $kdbx->composite_key($key);
$key = $kdbx->composite_key($primitive);

Construct a File::KDBX::Key::Composite from a Key or primitive. See new in File::KDBX::Key for what that primitive can be. If the primitive doesn't represent a composite key, it'll get wrapped. Fancy ✨

You generally don't need to call this directly either. The loader and dumper use it to transform a master key into a raw encryption key.

kdf

$kdf = $kdbx->kdf(%options);
$kdf = $kdbx->kdf(\%parameters, %options);

Get a File::KDBX::KDF (that's a key derivation function, for the uninitiated 👑).

Options:

params — KDF parameters, same as \%parameters (default: value of kdf_parameters)

cipher

$cipher = $kdbx->cipher(key => $key);
$cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);

Get a File::KDBX::Cipher capable of encrypting and decrypting the body of a database file. Main character energy 🎀

A key is required. This should be a raw encryption key made up of a fixed number of octets (depending on the cipher) — not a File::KDBX::Key and not a primitive. Don't try to sneak one of those in, it's giving wrong type.

If not passed, the UUID comes from $kdbx->headers->{cipher_id} and the encryption IV comes from $kdbx->headers->{encryption_iv}.

You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt KDBX files.

random_stream

$cipher = $kdbx->random_stream;
$cipher = $kdbx->random_stream(id => $stream_id, key => $key);

Get a File::KDBX::Cipher::Stream for decrypting and encrypting protected values. Scrambling the good stuff 🔥

If not passed, the ID and encryption key come from $kdbx->headers->{inner_random_stream_id} and $kdbx->headers->{inner_random_stream_key} (respectively) for KDBX3 files, and from $kdbx->inner_headers->{inner_random_stream_key} and $kdbx->inner_headers->{inner_random_stream_id} (respectively) for KDBX4 files.

You generally don't need to call this directly. The loader and dumper use it to scramble protected strings.

🌈 RECIPES 🌈

Create a new database

my $kdbx = File::KDBX->new;

my $group = $kdbx->add_group(name => 'Passwords);
my $entry = $group->add_entry(
    title    => 'WayneCorp',
    username => 'bwayne',
    password => 'iambatman',
    url      => 'https://example.com/login'
);
$entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');

$kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');

Read an existing database

my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
$kdbx->unlock;  # cause $entry->password below to be defined

$kdbx->entries->each(sub($entry, @) {
    say 'Found password for: ', $entry->title;
    say '  Username: ', $entry->username;
    say '  Password: ', $entry->password;
});

Search for entries

my @entries = $kdbx->entries(searching => 1)
    ->grep(title => 'WayneCorp')
    ->each;     # return all matches

The searching option limits results to only entries within groups with searching enabled. Other options are also available — go look at entries. And see QUERY for many more query examples, bestie, there's a whole treasure chest in there 💖

Search for entries by auto-type window association

my $window_title = 'WayneCorp - Mozilla Firefox';

my $entries = $kdbx->entries(auto_type => 1)
    ->filter(sub {
        my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
        return [$_, $ata->{keystroke_sequence}] if $ata;
    })
    ->each(sub {
        my ($entry, $keys) = @$_;
        say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
    });

Example output:

Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}

Remove entries from a database

$kdbx->entries
    ->grep(notes => {'=~' => qr/too old/i})
    ->each(sub { $_->recycle });

Recycle all entries with the string too old appearing in the Notes string. Bye bye 👋

Remove empty groups

$kdbx->groups(algorithm => 'dfs')
    ->where(-true => 'is_empty')
    ->each('remove');

With the search/iteration algorithm set to dfs, groups will be ordered deepest first and the root group will be last. This lets you remove groups that only contain empty groups. Chef's kiss ordering 🧚

This can also be done with one call to remove_empty_groups — way less typing, if that's your vibe.

🛡️ SECURITY 🛡️

Okay bestie, this is the part where we get serious for a sec, because literally one of the biggest threats to your database security is how easy it is to brute-force your encryption key. 💀 Brute-force protection lives and dies by two things:

Using unguessable passwords, passphrases and key files. 🔑
Using a brute-force resistent key derivation function. 🧱

The first one? That's all on you, babe. This module does not enforce strong master keys. Nobody's gonna come hold your hand and make you pick a good one — it is up to you to pick or generate strong keys. No cap. 🫶

The KDBX format lets you tune the key derivation function, and the whole idea is: you want every single brute-force attempt to be expensive (expensive in time, in CPU usage, or in memory usage). That way, if someone has to make a ton of attempts — which is exactly what happens when you've got a strong master key — it gets really, really expensive for them. 😌

How expensive you want each attempt to be? Up to you. It can totally depend on the application.

This and other KDBX-related security issues are covered way more in depth here: https://keepass.info/help/base/security.html

And here are the other security risks you should be thinking about, bestie:

🔐 Cryptography 🔐

This distribution uses the excellent CryptX and Crypt::Argon2 packages to handle all the crypto-related functions. So a lot of the security depends on how good those dependencies are. Luckily these modules are maintained and appear to have good track records. ✨

The KDBX format has evolved over time to incorporate improved security practices and cryptographic functions. This package uses the following functions for authentication, hashing, encryption and random number generation:

AES-128 (legacy) 🫣
AES-256 👑
Argon2d & Argon2id 💪
CBC block mode
HMAC-SHA256
SHA256
SHA512
Salsa20 & ChaCha20
Twofish 🐟

At the time of this writing, I am not aware of any successful attacks against any of these functions. These are among the most-analyzed and widely-adopted crypto functions available. So like, it's giving very well-audited. 🌈

The KDBX format allows the body cipher and key derivation function to be configured. If a flaw is discovered in one of these functions, you can hopefully just switch to a better function without needing to update this software. And a later software release may phase out the use of any functions which are no longer secure. So the vibes can be re-vibed, iykyk. 🧚

🧠 Memory Protection 🧠

Keeping secret information unencrypted in system memory for longer than you need to? Not the move. The address space of your program can generally be read by a user with elevated privileges on the system. And if your system is memory-constrained or goes into a hibernation mode, the contents of your address space could get written to a disk where it might be persisted for a long time. 😭

There might be system-level things you can do to reduce your risk, like using swap encryption and limiting system access to your program's address space while your program is running.

File::KDBX helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until accessed and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet. 🎀

For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key is available to be found out. But at least there is the chance that the encryption key and the encrypted secrets won't both be paged out together while memory-constrained. 🤷♀️

Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly, and it's difficult know when perl makes a copy of a secret in order to be able to zero it out later. It might be impossible. The good news is that perls with SvPV copy-on-write (enabled by default beginning with perl 5.20) are much better in this regard. With COW, it's mostly possible to know what operations will cause perl to copy the memory of a scalar string, and the number of copies will be significantly reduced. There is a unit test named t/memory-protection.t in this distribution that can be run on POSIX systems to determine how well File::KDBX memory protection is working. 🧪

Memory protection also depends on how your application handles secrets. If your app code is handling scalar strings with secret information, it's up to you to make sure its memory is zeroed out when no longer needed. "erase" in File::KDBX::Util et al. provide some tools to help accomplish this. Or if you're not too concerned about the risks memory protection is meant to mitigate, then maybe don't worry about it. The security policy of File::KDBX is to try hard to keep secrets protected while in memory so that your app might claim a high level of security, in case you care about that. 💅

There are some memory protection strategies that File::KDBX does NOT use today but could in the future:

Many systems allow programs to mark unswappable pages. Secret information should ideally be stored in such pages. You could potentially use mlockall(2) (or equivalent for your system) in your own application to prevent the entire address space from being swapped.

Some systems provide special syscalls for storing secrets in memory while keeping the encryption key outside of the program's address space, like "CryptProtectMemory" for Windows. This could be a good option, though unfortunately not portable.

🔎 QUERY 🔎

So you wanna find things in a KDBX database? Bestie, the move is a filtered iterator. If you have an iterator — like one returned by "entries", "groups" or even "objects" — you can filter it using "where" in File::KDBX::Iterator.

my $filtered_entries = $kdbx->entries->where(\&query);

A "\&query" is just a subroutine that you can either write yourself or have generated for you from either a "Simple Expression" or "Declarative Syntax". It's easier to have your query generated, so I'll cover that first. 💖

✍️ Simple Expression ✍️

A simple expression is mostly compatible with the KeePass 2 implementation described here https://keepass.info/help/base/search.html#mode_se.

An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in double quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term on at least one of the given fields.

So a simple expression is something like what you might type into a search engine. You can generate a simple expression query using "simple_expression_query" in File::KDBX::Util or by passing the simple expression as a scalar reference to "where".

To search for all entries in a database with the word canyon appearing anywhere in the title:

my $entries = $kdbx->entries->where(\'canyon', qw[title]);

Notice the first argument is a scalarref. This disambiguates a simple expression from other types of queries covered below. 👀

As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that has the words red and canyon anywhere in the title:

my $entries = $kdbx->entries->where(\'red canyon', qw[title]);

Each term in the simple expression must be found for an entry to match.

To search for entries with red in the title but not canyon, just prepend canyon with a minus sign:

my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);

To search over multiple fields simultaneously, just list them all. ✨ To search for entries with grocery (but not Foodland) in the title or notes:

my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);

The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use just about any binary comparison operator that perl supports. To specify an operator, list it after the simple expression. For example, to search for any entry that has been used at least five times:

my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);

It helps to read it right-to-left, like "usage_count is greater than or equal to 5". 🧠

If you find the disambiguating structures to be distracting or confusing, you can also use the "simple_expression_query" in File::KDBX::Util function as a more intuitive alternative. The following example is equivalent to the previous:

my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));

🗂️ Declarative Syntax 🗂️

Structuring a declarative query is similar to "WHERE CLAUSES" in SQL::Abstract, but you don't have to be familiar with that module. Just learn by examples here. 📚

To search for all entries in a database titled My Bank:

my $entries = $kdbx->entries->where({ title => 'My Bank' });

The query here is { title => 'My Bank' }. A hashref can contain key-value pairs where the key is an attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's attribute to be to consider it a match. In this case, the attribute we're using as our match criteria is "title" in File::KDBX::Entry, a text field. If an entry has its title attribute equal to My Bank, it's a match. 💅

A hashref can contain multiple attributes. The search candidate will be a match if all of the specified attributes are equal to their respective values. For example, to search for all entries with a particular URL AND username:

my $entries = $kdbx->entries->where({
    url      => 'https://example.com',
    username => 'neo',
});

To search for entries matching any criteria, just change the hashref to an arrayref. To search for entries with a particular URL OR username:

my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
    url      => 'https://example.com',
    username => 'neo',
]);

You can use different operators to test different types of attributes. The "icon_id" in File::KDBX::Entry attribute is a number, so we should use a number comparison operator. To find entries using the smartphone icon:

my $entries = $kdbx->entries->where({
    icon_id => { '==', ICON_SMARTPHONE },
});

Note: "ICON_SMARTPHONE" in File::KDBX::Constants is just a constant from File::KDBX::Constants. It isn't special to this example or to queries generally. We could have just used a literal number.

The important thing to notice here is how we wrapped the condition in another hashref with a single key-value pair where the key is the name of an operator and the value is the thing to match against. The supported operators are:

"eq" — String equal
"ne" — String not equal
"lt" — String less than
"gt" — String greater than
"le" — String less than or equal
"ge" — String greater than or equal
"==" — Number equal
"!=" — Number not equal
"<" — Number less than
">" — Number greater than
"<=" — Number less than or equal
">=" — Number less than or equal
=~ — String match regular expression
!~ — String does not match regular expression
! — Boolean false
!! — Boolean true

And the rest of the special-operator squad:

-true — Boolean true
-false — Boolean false
-not — Boolean false (aka an alias for -false)
-defined — Is defined
-undef — Is not defined
-empty — Is empty
-nonempty — Is not empty
-or — Logical or
-and — Logical and

Okay bestie, let's do another example, this time with an explicit operator 💅 Say you want every group except one specific group (the one identified by its uuid in File::KDBX::Group). You'd reach for the ne (string not equal) operator:

my $groups = $kdbx->groups->where(
    uuid => {
        'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
    },
);

Note: uuid in File::KDBX::Util is just a lil utility function that converts a UUID from its pretty form into bytes 🎀 It's not special to this example or to queries in general. You absolutely could've written it with a literal like "\x59\x6f\x75\x20\x61...", but ngl that's so much harder to read.

Notice we searched for groups this time — and finding groups works exactly the same way it does for entries. Slay.

Also notice we did not wrap the query in hashref curly-braces or arrayref square-braces. Those are optional ✨ By default it only matches ALL attributes (as if there were curly-braces).

Testing the truthiness of an attribute is a little bit of a different vibe, because it's not a binary operation. To find every entry with the password quality check disabled:

my $entries = $kdbx->entries->where('!' => 'quality_check');

See how the string after the operator is the attribute name this time, not a value to compare against? Yeah. And to test that a boolean value is true, use the !! operator (or -true, if !! feels a lil too weird for your taste 🫶):

my $entries = $kdbx->entries->where('!!'  => 'quality_check');
my $entries = $kdbx->entries->where(-true => 'quality_check');  # same thing

Yes babes, there's also a -false and a -not if you prefer one of those over !. Now here's the juicy part: -false and -not (along with -true) are also special in that you can use them to invert the logic of a subquery. These two are logically equivalent:

my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });

These special operators get so much more useful when you combine them with two more special operators: -and and -or 🔥 With those, you can construct way more interesting queries with groups of logic. For example:

my $entries = $kdbx->entries->where({
    title   => { '=~', qr/bank/ },
    -not    => {
        -or     => {
            notes   => { '=~', qr/business/ },
            icon_id => { '==', ICON_TRASHCAN_FULL },
        },
    },
});

In English 🌸 find entries where the word bank appears anywhere in the title, but that also do not have either the word business in the notes or are using the full trashcan icon.

🧚 Subroutine Query 🧚

And lastly, like I said at the top, you can completely ignore all of this and just write your own subroutine. Your subroutine gets called once for each object being searched over. It should match the candidate against whatever criteria you want, and return true if it matches or false to skip it. To do that, just pass your subroutine coderef to where.

So to review all the different types of queries, these are all equivalent to finding every entry in the database titled My Bank:

my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]);     # simple expression
my $entries = $kdbx->entries->where(title => 'My Bank');                # declarative syntax
my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' });    # subroutine query

Trivial example, sure, but of course your subroutine can be arbitrarily complex 💜

Every query mechanism described in this section is just a tool, each one with its own set of limitations. If the tools are getting in your way, you can always just iterate over the contents of a database and implement your own query logic, like this:

my $entries = $kdbx->entries;
while (my $entry = $entries->next) {
    if (wanted($entry)) {
        do_something($entry);
    }
    else {
        ...
    }
}

🌈 Iteration 🌈

Iterators are the built-in way to navigate or walk the database tree. You get an iterator from entries, groups and objects. You can specify the search algorithm to iterate over objects in different orders using the algorithm option, which can be one of these constants:

ITERATION_IDS — Iterative deepening search (this is the default 👑)
ITERATION_DFS — Depth-first search
ITERATION_BFS — Breadth-first search

When iterating over objects generically, groups always come before their direct entries (if any). And when the history option is used, current entries always come before historical entries.

So if you have a database tree like this:

Database
- Root
    - Group1
        - EntryA
        - Group2
            - EntryB
    - Group3
        - EntryC

Then here's the tea 🍓:

IDS order of groups is: Root, Group1, Group2, Group3
IDS order of entries is: EntryA, EntryB, EntryC
IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
DFS order of groups is: Group2, Group1, Group3, Root
DFS order of entries is: EntryB, EntryA, EntryC
DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
BFS order of groups is: Root, Group1, Group3, Group2
BFS order of entries is: EntryA, EntryC, EntryB
BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB

🔄 SYNCHRONIZING 🔄

TODO ✨ This is a planned feature, not yet implemented. (Not me hyping up vaporware, it's literally in the original.)

💀 ERRORS 💀

Errors in this package are constructed as File::KDBX::Error objects and propagated using perl's built-in mechanisms. Fatal errors get propagated using die LIST in perlfunc, and non-fatal errors (a.k.a. warnings) get propagated using warn LIST in perlfunc, all while adhering to perl's warnings system. If you already know these mechanisms, you can totally skip this section, bestie, no hard feelings 🙈

You can catch fatal errors using eval BLOCK in perlfunc (or something like Try::Tiny), and non-fatal errors using $SIG{__WARN__} (see "%SIG" in perlvar). Examples:

use File::KDBX::Error qw(error);

my $key = '';   # uh oh
eval {
    $kdbx->load_file('whatever.kdbx', $key);
};
if (my $error = error($@)) {
    handle_missing_key($error) if $error->type eq 'key.missing';
    $error->throw;
}

or using Try::Tiny:

try {
    $kdbx->load_file('whatever.kdbx', $key);
}
catch {
    handle_error($_);
};

Catching non-fatal errors:

my @warnings;
local $SIG{__WARN__} = sub { push @warnings, $_[0] };

$kdbx->load_file('whatever.kdbx', $key);

handle_warnings(@warnings) if @warnings;

By default perl prints warnings to STDERR if you don't catch them. But if you don't want to catch them and you also don't want them printed to STDERR, you can suppress them lexically (perl v5.28 or higher required, no cap):

{
    no warnings 'File::KDBX';
    ...
}

or locally:

{
    local $File::KDBX::WARNINGS = 0;
    ...
}

or globally, for your whole program:

$File::KDBX::WARNINGS = 0;

You cannot suppress fatal errors, and if you don't catch them your program will exit. Periodt. 😭

🌸 ENVIRONMENT 🌸

This software will alter its behavior depending on the value of certain environment variables:

PERL_FILE_KDBX_XS — Do not use File::KDBX::XS if false (default: true)
PERL_ONLY — Do not use File::KDBX::XS if true (default: false)
NO_FORK — Do not fork if true (default: false)

🦋 SEE ALSO 🦋

KeePass Password Safe https://keepass.info/ — The original KeePass
KeePassXC https://keepassxc.org/ — Cross-Platform Password Manager written in C++
File::KeePass has overlapping functionality. It's good but has a backlog of some pretty critical bugs and lacks support for newer KDBX features. (I said what I said 💅)

🎀 BUGS 🎀

Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/File-KDBX/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. That part's not optional, it's literally the whole point, iykyk 🫶

👑 AUTHOR 👑

Charles McGarvey <ccm@cpan.org>

💖 COPYRIGHT AND LICENSE 💖

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

And that's the whole page, bestie — we did it, we ate and left no crumbs 🌈⭐ This one's perl v5.40.1 for File::KDBX(3pm), dated 2025-05-04. Go forth and encrypt your secrets, you gorgeous main character 💅✨🦋

📦 where this page comes from

debian trixie: libfile-kdbx-perl 0.906-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libfile-kdbx-perl 0.906-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libfile-kdbx-perl 0.906-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

File::KDBX(3pm)

✨ File::KDBX ✨

🎀 NAME 🎀

🌸 VERSION 🌸

🦋 SYNOPSIS 🦋

💜 DESCRIPTION 💜

🍓 Features 🍓

🧚 Introduction to KDBX 🧚

👑 ATTRIBUTES 👑

sig1

sig2

version

headers

inner_headers

meta

binaries

deleted_objects

raw

comment

cipher_id

compression_flags

master_seed

transform_seed

transform_rounds

encryption_iv

inner_random_stream_key

stream_start_bytes

inner_random_stream_id

kdf_parameters

generator

header_hash

database_name

database_name_changed

database_description

database_description_changed

default_username

default_username_changed

color

master_key_changed

master_key_change_rec

master_key_change_force

custom_icons

recycle_bin_enabled

recycle_bin_uuid

recycle_bin_changed

entry_templates_group

entry_templates_group_changed

last_selected_group

last_top_visible_group

history_max_items

history_max_size

maintenance_history_days

settings_changed

protect_title

protect_username

protect_password

protect_url

protect_notes