Provided by: libfile-kdbx-perl_0.906-2_all 
NAME
File::KDBX::Entry - A KDBX database entry
VERSION
version 0.906
DESCRIPTION
An entry in a KDBX database is a record that can contains strings (also called "fields")
and binaries (also called "files" or "attachments"). Every string and binary has a key or
name. There is a default set of strings that every entry has:
• Title
• UserName
• Password
• URL
• Notes
Beyond this, you can store any number of other strings and any number of binaries that you
can use for whatever purpose you want.
There is also some metadata associated with an entry. Each entry in a database is
identified uniquely by a UUID. An entry can also have an icon associated with it, and
there are various timestamps. Take a look at the attributes to see what's available.
A File::KDBX::Entry is a subclass of File::KDBX::Object. View its documentation to see
other attributes and methods available on entries.
Placeholders
Entry string and auto-type key sequences can have placeholders or template tags that can
be replaced by other values. Placeholders can appear like "{PLACEHOLDER}". For example, a
URL string might have a value of "http://example.com?user={USERNAME}". "{USERNAME}" is a
placeholder for the value of the UserName string of the same entry. If the UserName string
had a value of "batman", the URL string would expand to "http://example.com?user=batman".
Some placeholders take an argument, where the argument follows the tag after 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.
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
• ☑ "{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 Year component of the current UTC time
• ☑ "{DT_UTC_SECOND}" - Second component of the current UTC time
If the current date and time is "2012-07-25 17:05:34", the "simple" form would be
20120725170534.
Special Key Placeholders
Certain placeholders for use in auto-type key sequences are not supported for replacement,
but they will remain as-is so that an auto-type engine (not included) can parse and
replace them with the appropriate virtual key presses. For completeness, here is 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 these that remain unimplemented, such as "{CLIPBOARD}", cannot be implemented
portably. Some of these I haven't implemented (yet) just because they don't seem very
useful. You can create your own placeholder to augment the list of default supported
placeholders or to replace a built-in placeholder handler. To create a placeholder, just
set it in the %File::KDBX::PLACEHOLDERS hash. For example:
$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 is "undef". An entry is in context if, for example, the
placeholder is 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 is expected to receive an
argument. During expansion, everything after the colon and before the end of the
placeholder is 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 than take one. I.e. The placeholder handler won't
be called if there is 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):
$File::KDBX::PLACEHOLDERS{'RAND'} = $File::KDBX::PLACEHOLDERS{'RAND:'} = sub {
(undef, my $arg) = @_;
return defined $arg ? rand($arg) : rand;
};
You can also remove placeholder handlers. If you want to 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 configuration storage isn't completely standardized, but this module
supports two predominant configuration 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.
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: The 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.
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
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 software is copyright (c) 2022 by Charles McGarvey.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.