File::...::Entry(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::...::Entry <span>—</span> the manual, bestie edition 🎀

okay so you're looking at File::...::Entry(3pm) — that's a User Contributed Perl Documentation page, which basically means a real one of us wrote it and shipped it. 🫶

✨ NAME ✨

File::KDBX::Entry — a KDBX database entry 💅

like. that's the whole vibe. it's an entry. it lives in a KDBX database. it's giving "the little guy inside your KeePass vault holding your passwords." 👑

🌸 VERSION 🌸

version 0.906 ⭐

this is the version of the module this page describes, bestie — not the version of your feelings about it.

more parts incoming, don't go anywhere 💜

💖 DESCRIPTION 💖

Okay bestie, so an entry in a KDBX database is basically a record — and a record can hold strings (we also call these "fields") and binaries (aka "files" or "attachments"). Every string and every binary has a key, or a name. And like, there's a default lil' set of strings that every entry just has:

Title
UserName
Password
URL
Notes

And beyond that? You can stash literally any number of other strings and any number of binaries for whatever your heart desires. No cap. 🌈

There's also some metadata riding along with an entry. Every entry in a database is identified uniquely by a UUID ✨. An entry can also have an icon attached to it, plus there are various timestamps. Go peek at the attributes to see what's on the menu.

A File::KDBX::Entry is a subclass of File::KDBX::Object. Read its docs to see the other attributes and methods you get on entries 👑

🎀 Placeholders 🎀

Entry strings and auto-type key sequences can have placeholders — a.k.a. template tags — that get swapped out for other values. Placeholders show up looking like {PLACEHOLDER}. For example, a URL string might hold http://example.com?user={USERNAME}. That {USERNAME} is a placeholder for the value of the UserName string of the same entry. So if UserName was batman, the URL string would expand to http://example.com?user=batman. Chef's kiss 💅

Some placeholders take an argument. The argument comes after the tag, following a colon but before the closing brace, like {PLACEHOLDER:ARGUMENT}.

Placeholders are documented in the KeePass Help Center — https://keepass.info/help/base/placeholders.html. This software supports many (but not all) of the placeholders documented there. Not me being honest about the gaps 🙈

Entry Placeholders

☑ {TITLE} — Title string
☑ {USERNAME} — UserName string
☑ {PASSWORD} — Password string
☑ {NOTES} — Notes string
☑ {URL} — URL string
☑ {URL:SCM} / {URL:SCHEME}
☑ {URL:USERINFO}
☑ {URL:USERNAME}
☑ {URL:PASSWORD}
☑ {URL:HOST}
☑ {URL:PORT}
☑ {URL:PATH}
☑ {URL:QUERY}
☑ {URL:FRAGMENT} / {URL:HASH}
☑ {URL:RMVSCM} / {URL:WITHOUTSCHEME}
☑ {S:Name} — custom string, where Name is the name or key of the string
☑ {UUID} — identifier (32 hexidecimal characters)
☑ {HMACOTP} — generate an HMAC-based one-time password (its counter will be incremented)
☑ {TIMEOTP} — generate a time-based one-time password
☑ {GROUP_NOTES} — notes of the parent group
☑ {GROUP_PATH} — full path of the parent group
☑ {GROUP} — name of the parent group

Field References

☑ {REF:Wanted@SearchIn:Text} — see "resolve_reference" in File::KDBX

File path Placeholders

☑ {APPDIR} — program directory path
☑ {FIREFOX} — path to the Firefox browser executable
☑ {GOOGLECHROME} — path to the Chrome browser executable
☑ {INTERNETEXPLORER} — path to the Firefox browser executable (fr, the page says Firefox here, we do not make the rules 💀)
☑ {OPERA} — path to the Opera browser executable
☑ {SAFARI} — path to the Safari browser executable
☒ {DB_PATH} — full file path of the database
☒ {DB_DIR} — directory path of the database
☒ {DB_NAME} — file name (including extension) of the database
☒ {DB_BASENAME} — file name (excluding extension) of the database
☒ {DB_EXT} — file name extension
☑ {ENV_DIRSEP} — directory separator
☑ {ENV_PROGRAMFILES_X86} — one of %ProgramFiles(x86)% or %ProgramFiles%

Date and Time Placeholders

☑ {DT_SIMPLE} — current local date and time as a sortable string
☑ {DT_YEAR} — year component of the current local date
☑ {DT_MONTH} — month component of the current local date
☑ {DT_DAY} — day component of the current local date
☑ {DT_HOUR} — hour component of the current local time
☑ {DT_MINUTE} — minute component of the current local time
☑ {DT_SECOND} — second component of the current local time
☑ {DT_UTC_SIMPLE} — current UTC date and time as a sortable string
☑ {DT_UTC_YEAR} — year component of the current UTC date
☑ {DT_UTC_MONTH} — month component of the current UTC date
☑ {DT_UTC_DAY} — day component of the current UTC date
☑ {DT_UTC_HOUR} — hour component of the current UTC time
☑ {DT_UTC_MINUTE} — minute component of the current UTC time (the original page says "Minute Year" right here, iconic lil' typo, but yeah — it's the minute 🙈)
☑ {DT_UTC_SECOND} — second component of the current UTC time

So like, if the current date and time is 2012-07-25 17:05:34, the "simple" form would be 20120725170534.

Special Key Placeholders

Okay so certain placeholders meant for auto-type key sequences are not supported for replacement — they stay as-is so an auto-type engine (not included, bestie) can parse them and swap in the right virtual key presses. For completeness, here's the list that the KeePass program claims to support:

{TAB}, {ENTER}, {UP}, {DOWN}, {LEFT}, {RIGHT}, {HOME}, {END}, {PGUP}, {PGDN}, {INSERT}, {DELETE}, {SPACE}

{BACKSPACE}, {BREAK}, {CAPSLOCK}, {ESC}, {WIN}, {LWIN}, {RWIN}, {APPS}, {HELP}, {NUMLOCK}, {PRTSC}, {SCROLLLOCK}

{F1}, {F2}, {F3}, {F4}, {F5}, {F6}, {F7}, {F8}, {F9}, {F10}, {F11}, {F12}, {F13}, {F14}, {F15}, {F16}

{ADD}, {SUBTRACT}, {MULTIPLY}, {DIVIDE}, {NUMPAD0}, {NUMPAD1}, {NUMPAD2}, {NUMPAD3}, {NUMPAD4}, {NUMPAD5}, {NUMPAD6}, {NUMPAD7}, {NUMPAD8}, {NUMPAD9}

Miscellaneous Placeholders

☒ {BASE}
☒ {BASE:SCM} / {BASE:SCHEME}
☒ {BASE:USERINFO}
☒ {BASE:USERNAME}
☒ {BASE:PASSWORD}
☒ {BASE:HOST}
☒ {BASE:PORT}
☒ {BASE:PATH}
☒ {BASE:QUERY}
☒ {BASE:FRAGMENT} / {BASE:HASH}
☒ {BASE:RMVSCM} / {BASE:WITHOUTSCHEME}
☒ {CLIPBOARD-SET:/Text/}
☒ {CLIPBOARD}
☒ {CMD:/CommandLine/Options/}
☑ {C:Comment} — comments are simply replaced by nothing
☑ {ENV:} and %ENV% — environment variables
☒ {GROUP_SEL_NOTES}
☒ {GROUP_SEL_PATH}
☒ {GROUP_SEL}
☒ {NEWPASSWORD}
☒ {NEWPASSWORD:/Profile/}
☒ {PASSWORD_ENC}
☒ {PICKCHARS}
☒ {PICKCHARS:Field:Options}
☒ {PICKFIELD}
☒ {T-CONV:/Text/Type/}
☒ {T-REPLACE-RX:/Text/Type/Replace/}

Some of the ones still unimplemented, like {CLIPBOARD}, just can't be implemented portably. And some? Not implemented (yet) simply because they don't seem very useful. 🤷

You can make your own placeholder to add to the default lineup, or to replace a built-in placeholder handler. To create a placeholder, just set it in the %File::KDBX::PLACEHOLDERS hash. Like so:

$File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER'} = sub {
    my ($entry) = @_;
    ...;
};

If the placeholder is expanded in the context of an entry, $entry is the File::KDBX::Entry object in context. Otherwise it's undef. An entry is in context if, for example, the placeholder sits in an entry's strings or auto-type key sequences.

$File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER:'} = sub {
    my ($entry, $arg) = @_;         #    ^ Notice the colon here
    ...;
};

If the name of the placeholder ends in a colon, then it's expected to receive an argument. During expansion, everything after the colon and before the end of the placeholder gets passed to your placeholder handler subroutine. So if the placeholder is {MY_PLACEHOLDER:whatever}, $arg will have the value whatever ✨

An argument is required for placeholders that take one. I.e. the placeholder handler won't even get called if there's no argument. If you want a placeholder to support an optional argument, you'll need to set the placeholder both with and without a colon (or they could be different subroutines, queen's choice):

$File::KDBX::PLACEHOLDERS{'RAND'} = $File::KDBX::PLACEHOLDERS{'RAND:'} = sub {
    (undef, my $arg) = @_;
    return defined $arg ? rand($arg) : rand;
};

You can also remove placeholder handlers. And if you wanna disable placeholder expansion entirely? Just delete all the handlers:

%File::KDBX::PLACEHOLDERS = ();

🔐 One-time Passwords 🔐

An entry can be configured to generate one-time passwords — both HOTP (HMAC-based) and TOTP (time-based). The config storage isn't completely standardized, but this module supports two predominant config styles:

KeePass 2 — https://keepass.info/help/base/placeholders.html#otp
KeePassXC

NOTE: to use this feature, you must install the suggested dependency: - Pass::OTP

To configure TOTP in the KeePassXC style, there is only one string to set: "otp". The value should be any valid otpauth URI. When generating an OTP, all of the relevant OTP properties are parsed from the URI. slay, one string 💅

To configure TOTP in the KeePass 2 style, set the following strings:

"TimeOtp-Algorithm" — cryptographic algorithm, one of "HMAC-SHA-1" (default), "HMAC-SHA-256" and "HMAC-SHA-512"
"TimeOtp-Length" — number of digits each one-time password is (default: 6, maximum: 8)
"TimeOtp-Period" — time-step size in seconds (default: 30)
"TimeOtp-Secret" — text string secret, OR
"TimeOtp-Secret-Hex" — hexidecimal-encoded secret, OR
"TimeOtp-Secret-Base32" — Base32-encoded secret (most common), OR
"TimeOtp-Secret-Base64" — Base64-encoded secret

To configure HOTP in the KeePass 2 style, set the following strings:

"HmacOtp-Counter" — counting value in decimal, starts on 0 by default and increments when "hmac_otp" is called
"HmacOtp-Secret" — text string secret, OR
"HmacOtp-Secret-Hex" — hexidecimal-encoded secret, OR
"HmacOtp-Secret-Base32" — Base32-encoded secret (most common), OR
"HmacOtp-Secret-Base64" — Base64-encoded secret

NOTE: those multiple "Secret" strings are simply a way to store a secret in different formats. Only one of these should actually be set — or an error will be thrown. Pick a lane bestie 🚨

Here's a basic example:

$entry->string(otp => 'otpauth://totp/Issuer:user?secret=NBSWY3DP&issuer=Issuer');
# OR
$entry->string('TimeOtp-Secret-Base32' => 'NBSWY3DP');

my $otp = $entry->time_otp;

✨ ATTRIBUTES ✨

foreground_color

Text color represented as a string of the form #000000.

background_color

Background color represented as a string of the form #FFFFFF.

override_url

TODO 💀 (literally just a TODO, bestie.)

auto_type_enabled

Whether or not the entry is eligible to be matched for auto-typing.

auto_type_obfuscation

Whether or not to use some kind of obfuscation when sending keystroke sequences to applications.

auto_type_default_sequence

The default auto-type keystroke sequence.

auto_type_associations

An array of window title / keystroke sequence associations.

{
    window              => 'Example Window Title',
    keystroke_sequence  => '{USERNAME}{TAB}{PASSWORD}{ENTER}',
}

Keystroke sequences can have "Placeholders", most commonly {USERNAME} and {PASSWORD}.

quality_check

Boolean indicating whether the entry password should be tested for weakness and show up in reports.

strings

Hash with entry strings, including the standard strings as well as any custom ones.

{
    # Every entry has these five strings:
    Title    => { value => 'Example Entry' },
    UserName => { value => 'jdoe' },
    Password => { value => 's3cr3t', protect => true },
    URL      => { value => 'https://example.com' }
    Notes    => { value => '' },
    # May also have custom strings:
    MySystem => { value => 'The mainframe' },
}

There are methods available to provide more convenient access to strings, including string, string_value, expand_string_value and string_peek.

binaries

Files or attachments. Binaries are similar to strings except they have a value of bytes instead of test characters.

{
    'myfile.txt'    => {
        value   => '...',
    },
    'mysecrets.txt' => {
        value   => '...',
        protect => true,
    },
}

There are methods available to provide more convenient access to binaries, including binary and binary_value.

history

Array of historical entries. Historical entries are prior versions of the same entry so they all share the same UUID with the current entry.

notes

Alias for the Notes string value.

password

Alias for the Password string value.

title

Alias for the Title string value.

url

Alias for the URL string value.

username

Aliases for the UserName string value.

🌸 METHODS 🌸

string

\%string = $entry->string($string_key);

$entry->string($string_key, \%string);
$entry->string($string_key, %attributes);
$entry->string($string_key, $value); # same as: value => $value

Get or set a string. Every string has a unique (to the entry) key and flags and so are returned as a hash structure. For example:

$string = {
    value   => 'Password',
    protect => true,    # optional
};

Every string should have a value (but might be undef due to memory protection) and these optional flags which might exist:

protect — Whether or not the string value should be memory-protected.

string_value

$string = $entry->string_value($string_key);

Access a string value directly. The arguments are the same as for string. Returns undef if the string is not set or is currently memory-protected. This is just a shortcut for:

my $string = do {
    my $s = $entry->string(...);
    defined $s ? $s->{value} : undef;
};

expand_string_value

$string = $entry->expand_string_value($string_key);

Same as string_value but will substitute placeholders and resolve field references. Any placeholders that do not expand to values are left as-is.

See "Placeholders".

Some placeholders (notably field references) require the entry be connected to a database and will throw an error if it is not.

expand_notes

Shortcut equivalent to ->expand_string_value('Notes').

expand_password

Shortcut equivalent to ->expand_string_value('Password').

expand_title

Shortcut equivalent to ->expand_string_value('Title').

expand_url

Shortcut equivalent to ->expand_string_value('URL').

expand_username

Shortcut equivalent to ->expand_string_value('UserName').

other_strings

$other = $entry->other_strings;
$other = $entry->other_strings($delimiter);

Get a concatenation of all non-standard string values. The default delimiter is a newline. This is is useful for executing queries to search for entities based on the contents of these other strings (if any).

string_peek

$string = $entry->string_peek($string_key);

Same as string_value but can also retrieve the value from protected-memory if the value is currently protected.

add_auto_type_association

$entry->add_auto_type_association(\%association);

Add a new auto-type association to an entry.

expand_keystroke_sequence

$string = $entry->expand_keystroke_sequence($keystroke_sequence);
$string = $entry->expand_keystroke_sequence(\%association);
$string = $entry->expand_keystroke_sequence;    # use default auto-type sequence

Get a keystroke sequence after placeholder expansion.

binary

\%binary = $entry->binary($binary_key);

$entry->binary($binary_key, \%binary);
$entry->binary($binary_key, %attributes);
$entry->binary($binary_key, $value); # same as: value => $value

Get or set a binary. Every binary has a unique (to the entry) key and flags and so are returned as a hash structure. For example:

$binary = {
    value   => '...',
    protect => true,    # optional
};

Every binary should have a value (but might be undef due to memory protection) and these optional flags which might exist:

protect — Whether or not the binary value should be memory-protected.

binary_value

$binary = $entry->binary_value($binary_key);

Access a binary value directly. The arguments are the same as for binary. Returns undef if the binary is not set or is currently memory-protected. This is just a shortcut for:

my $binary = do {
    my $b = $entry->binary(...);
    defined $b ? $b->{value} : undef;
};

hmac_otp

$otp = $entry->hmac_otp(%options);

Generate an HMAC-based one-time password, or undef if HOTP is not configured for the entry. The entry's strings generally must first be unprotected, just like when accessing the password. Valid options are:

counter — Specify the counter value

To configure HOTP, see "One-time Passwords".

time_otp

$otp = $entry->time_otp(%options);

Generate a time-based one-time password, or undef if TOTP is not configured for the entry. The entry's strings generally must first be unprotected, just like when accessing the password. Valid options are:

now — Specify the value for determining the time-step counter

To configure TOTP, see "One-time Passwords".

hmac_otp_uri, time_otp_uri

$uri_string = $entry->hmac_otp_uri;
$uri_string = $entry->time_otp_uri;

Get a HOTP or TOTP otpauth URI for the entry, if available.

To configure OTP, see "One-time Passwords".

size

$size = $entry->size;

Get the size (in bytes) of an entry.

NOTE: This is not an exact figure because there is no canonical serialization of an entry. This size should only be used as a rough estimate for comparison with other entries or to impose data size limitations.

history_size

$size = $entry->history_size;

Get the size (in bytes) of all historical entries combined.

prune_history

@removed_historical_entries = $entry->prune_history(%options);

Remove just as many older historical entries as necessary to get under the database limits. The limits are taken from the connected database (if any) or can be overridden with %options:

max_items — Maximum number of historical entries to keep (default: 10, no limit: -1)
max_size — Maximum total size (in bytes) of historical entries to keep (default: 6 MiB, no limit: -1)
max_age — Maximum age (in days) of historical entries to keep (default: 365, no limit: -1)

add_historical_entry

$entry->add_historical_entry($entry);

Add an entry to the history.

remove_historical_entry

$entry->remove_historical_entry($historical_entry);

Remove an entry from the history.

current_entry

$current_entry = $entry->current_entry;

Get an entry's current entry. If the entry itself is current (not historical), itself is returned.

is_current

$bool = $entry->is_current;

Get whether or not an entry is considered current (i.e. not historical). An entry is current if it is directly in the parent group's entry list.

is_historical

$bool = $entry->is_historical;

Get whether or not an entry is considered historical (i.e. not current).

This is just the inverse of is_current.

remove

$entry = $entry->remove;

Remove an entry from its parent group. If the entry is historical, remove it from the history of the current entry. If the entry is current, this behaves the same as "remove" in File::KDBX::Object.

searching_enabled

$bool = $entry->searching_enabled;

Get whether or not an entry may show up in search results. This is determine from the entry's parent group's "effective_enable_searching" in File::KDBX::Group value.

Throws if entry has no parent group or if the entry is not connected to a database.

💀 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.

👑 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 vibe, bestie! 💖 This page is from perl v5.40.1, dated 2025-05-04. Now go forth and slay those KDBX entries like the icon you are! ✨💅🦋

📦 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