1File::KDBX::Entry(3) User Contributed Perl Documentation File::KDBX::Entry(3)
2
6 File::KDBX::Entry - A KDBX database entry
7
9 version 0.906
10
12 An entry in a KDBX database is a record that can contains strings (also
13 called "fields") and binaries (also called "files" or "attachments").
14 Every string and binary has a key or name. There is a default set of
15 strings that every entry has:
16 • Title
18 • UserName
20 • Password
22 • URL
24 • Notes
26 Beyond this, you can store any number of other strings and any number
28 of binaries that you can use for whatever purpose you want.
29 There is also some metadata associated with an entry. Each entry in a
31 database is identified uniquely by a UUID. An entry can also have an
32 icon associated with it, and there are various timestamps. Take a look
33 at the attributes to see what's available.
34 A File::KDBX::Entry is a subclass of File::KDBX::Object. View its
36 documentation to see other attributes and methods available on entries.
37 Placeholders
39 Entry string and auto-type key sequences can have placeholders or
40 template tags that can be replaced by other values. Placeholders can
41 appear like "{PLACEHOLDER}". For example, a URL string might have a
42 value of "http://example.com?user={USERNAME}". "{USERNAME}" is a
43 placeholder for the value of the UserName string of the same entry. If
44 the UserName string had a value of "batman", the URL string would
45 expand to "http://example.com?user=batman".
46 Some placeholders take an argument, where the argument follows the tag
48 after a colon but before the closing brace, like
49 "{PLACEHOLDER:ARGUMENT}".
50 Placeholders are documented in the KeePass Help Center
52 <https://keepass.info/help/base/placeholders.html>. This software
53 supports many (but not all) of the placeholders documented there.
54 Entry Placeholders
56 • ☑ "{TITLE}" - Title string
58 • ☑ "{USERNAME}" - UserName string
60 • ☑ "{PASSWORD}" - Password string
62 • ☑ "{NOTES}" - Notes string
64 • ☑ "{URL}" - URL string
66 • ☑ "{URL:SCM}" / "{URL:SCHEME}"
68 • ☑ "{URL:USERINFO}"
70 • ☑ "{URL:USERNAME}"
72 • ☑ "{URL:PASSWORD}"
74 • ☑ "{URL:HOST}"
76 • ☑ "{URL:PORT}"
78 • ☑ "{URL:PATH}"
80 • ☑ "{URL:QUERY}"
82 • ☑ "{URL:FRAGMENT}" / "{URL:HASH}"
84 • ☑ "{URL:RMVSCM}" / "{URL:WITHOUTSCHEME}"
86 • ☑ "{S:Name}" - Custom string where "Name" is the name or key of the
88 string
89 • ☑ "{UUID}" - Identifier (32 hexidecimal characters)
91 • ☑ "{HMACOTP}" - Generate an HMAC-based one-time password (its
93 counter will be incremented)
94 • ☑ "{TIMEOTP}" - Generate a time-based one-time password
96 • ☑ "{GROUP_NOTES}" - Notes of the parent group
98 • ☑ "{GROUP_PATH}" - Full path of the parent group
100 • ☑ "{GROUP}" - Name of the parent group
102 Field References
104 • ☑ "{REF:Wanted@SearchIn:Text}" - See "resolve_reference" in
106 File::KDBX
107 File path Placeholders
109 • ☑ "{APPDIR}" - Program directory path
111 • ☑ "{FIREFOX}" - Path to the Firefox browser executable
113 • ☑ "{GOOGLECHROME}" - Path to the Chrome browser executable
115 • ☑ "{INTERNETEXPLORER}" - Path to the Firefox browser executable
117 • ☑ "{OPERA}" - Path to the Opera browser executable
119 • ☑ "{SAFARI}" - Path to the Safari browser executable
121 • ☒ "{DB_PATH}" - Full file path of the database
123 • ☒ "{DB_DIR}" - Directory path of the database
125 • ☒ "{DB_NAME}" - File name (including extension) of the database
127 • ☒ "{DB_BASENAME}" - File name (excluding extension) of the database
129 • ☒ "{DB_EXT}" - File name extension
131 • ☑ "{ENV_DIRSEP}" - Directory separator
133 • ☑ "{ENV_PROGRAMFILES_X86}" - One of "%ProgramFiles(x86)%" or
135 "%ProgramFiles%"
136 Date and Time Placeholders
138 • ☑ "{DT_SIMPLE}" - Current local date and time as a sortable string
140 • ☑ "{DT_YEAR}" - Year component of the current local date
142 • ☑ "{DT_MONTH}" - Month component of the current local date
144 • ☑ "{DT_DAY}" - Day component of the current local date
146 • ☑ "{DT_HOUR}" - Hour component of the current local time
148 • ☑ "{DT_MINUTE}" - Minute component of the current local time
150 • ☑ "{DT_SECOND}" - Second component of the current local time
152 • ☑ "{DT_UTC_SIMPLE}" - Current UTC date and time as a sortable
154 string
155 • ☑ "{DT_UTC_YEAR}" - Year component of the current UTC date
157 • ☑ "{DT_UTC_MONTH}" - Month component of the current UTC date
159 • ☑ "{DT_UTC_DAY}" - Day component of the current UTC date
161 • ☑ "{DT_UTC_HOUR}" - Hour component of the current UTC time
163 • ☑ "{DT_UTC_MINUTE}" Minute Year component of the current UTC time
165 • ☑ "{DT_UTC_SECOND}" - Second component of the current UTC time
167 If the current date and time is "2012-07-25 17:05:34", the "simple"
169 form would be 20120725170534.
170 Special Key Placeholders
172 Certain placeholders for use in auto-type key sequences are not
174 supported for replacement, but they will remain as-is so that an auto-
175 type engine (not included) can parse and replace them with the
176 appropriate virtual key presses. For completeness, here is the list
177 that the KeePass program claims to support:
178 "{TAB}", "{ENTER}", "{UP}", "{DOWN}", "{LEFT}", "{RIGHT}", "{HOME}",
180 "{END}", "{PGUP}", "{PGDN}", "{INSERT}", "{DELETE}", "{SPACE}"
181 "{BACKSPACE}", "{BREAK}", "{CAPSLOCK}", "{ESC}", "{WIN}", "{LWIN}",
183 "{RWIN}", "{APPS}", "{HELP}", "{NUMLOCK}", "{PRTSC}", "{SCROLLLOCK}"
184 "{F1}", "{F2}", "{F3}", "{F4}", "{F5}", "{F6}", "{F7}", "{F8}", "{F9}",
186 "{F10}", "{F11}", "{F12}", "{F13}", "{F14}", "{F15}", "{F16}"
187 "{ADD}", "{SUBTRACT}", "{MULTIPLY}", "{DIVIDE}", "{NUMPAD0}",
189 "{NUMPAD1}", "{NUMPAD2}", "{NUMPAD3}", "{NUMPAD4}", "{NUMPAD5}",
190 "{NUMPAD6}", "{NUMPAD7}", "{NUMPAD8}", "{NUMPAD9}"
191 Miscellaneous Placeholders
193 • ☒ "{BASE}"
195 • ☒ "{BASE:SCM}" / "{BASE:SCHEME}"
197 • ☒ "{BASE:USERINFO}"
199 • ☒ "{BASE:USERNAME}"
201 • ☒ "{BASE:PASSWORD}"
203 • ☒ "{BASE:HOST}"
205 • ☒ "{BASE:PORT}"
207 • ☒ "{BASE:PATH}"
209 • ☒ "{BASE:QUERY}"
211 • ☒ "{BASE:FRAGMENT}" / "{BASE:HASH}"
213 • ☒ "{BASE:RMVSCM}" / "{BASE:WITHOUTSCHEME}"
215 • ☒ "{CLIPBOARD-SET:/Text/}"
217 • ☒ "{CLIPBOARD}"
219 • ☒ "{CMD:/CommandLine/Options/}"
221 • ☑ "{C:Comment}" - Comments are simply replaced by nothing
223 • ☑ "{ENV:}" and "%ENV%" - Environment variables
225 • ☒ "{GROUP_SEL_NOTES}"
227 • ☒ "{GROUP_SEL_PATH}"
229 • ☒ "{GROUP_SEL}"
231 • ☒ "{NEWPASSWORD}"
233 • ☒ "{NEWPASSWORD:/Profile/}"
235 • ☒ "{PASSWORD_ENC}"
237 • ☒ "{PICKCHARS}"
239 • ☒ "{PICKCHARS:Field:Options}"
241 • ☒ "{PICKFIELD}"
243 • ☒ "{T-CONV:/Text/Type/}"
245 • ☒ "{T-REPLACE-RX:/Text/Type/Replace/}"
247 Some of these that remain unimplemented, such as "{CLIPBOARD}", cannot
249 be implemented portably. Some of these I haven't implemented (yet) just
250 because they don't seem very useful. You can create your own
251 placeholder to augment the list of default supported placeholders or to
252 replace a built-in placeholder handler. To create a placeholder, just
253 set it in the %File::KDBX::PLACEHOLDERS hash. For example:
254 $File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER'} = sub {
256 my ($entry) = @_;
257 ...;
258 };
259 If the placeholder is expanded in the context of an entry, $entry is
261 the File::KDBX::Entry object in context. Otherwise it is "undef". An
262 entry is in context if, for example, the placeholder is in an entry's
263 strings or auto-type key sequences.
264 $File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER:'} = sub {
266 my ($entry, $arg) = @_; # ^ Notice the colon here
267 ...;
268 };
269 If the name of the placeholder ends in a colon, then it is expected to
271 receive an argument. During expansion, everything after the colon and
272 before the end of the placeholder is passed to your placeholder handler
273 subroutine. So if the placeholder is "{MY_PLACEHOLDER:whatever}", $arg
274 will have the value whatever.
275 An argument is required for placeholders than take one. I.e. The
277 placeholder handler won't be called if there is no argument. If you
278 want a placeholder to support an optional argument, you'll need to set
279 the placeholder both with and without a colon (or they could be
280 different subroutines):
281 $File::KDBX::PLACEHOLDERS{'RAND'} = $File::KDBX::PLACEHOLDERS{'RAND:'} = sub {
283 (undef, my $arg) = @_;
284 return defined $arg ? rand($arg) : rand;
285 };
286 You can also remove placeholder handlers. If you want to disable
288 placeholder expansion entirely, just delete all the handlers:
289 %File::KDBX::PLACEHOLDERS = ();
291 One-time Passwords
293 An entry can be configured to generate one-time passwords, both HOTP
294 (HMAC-based) and TOTP (time-based). The configuration storage isn't
295 completely standardized, but this module supports two predominant
296 configuration styles:
297 • KeePass 2 <https://keepass.info/help/base/placeholders.html#otp>
299 • KeePassXC
301 NOTE: To use this feature, you must install the suggested dependency:
303 • Pass::OTP
305 To configure TOTP in the KeePassXC style, there is only one string to
307 set: "otp". The value should be any valid otpauth URI. When generating
308 an OTP, all of the relevant OTP properties are parsed from the URI.
309 To configure TOTP in the KeePass 2 style, set the following strings:
311 • "TimeOtp-Algorithm" - Cryptographic algorithm, one of "HMAC-SHA-1"
313 (default), "HMAC-SHA-256" and "HMAC-SHA-512"
314 • "TimeOtp-Length" - Number of digits each one-time password is
316 (default: 6, maximum: 8)
317 • "TimeOtp-Period" - Time-step size in seconds (default: 30)
319 • "TimeOtp-Secret" - Text string secret, OR
321 • "TimeOtp-Secret-Hex" - Hexidecimal-encoded secret, OR
323 • "TimeOtp-Secret-Base32" - Base32-encoded secret (most common), OR
325 • "TimeOtp-Secret-Base64" - Base64-encoded secret
327 To configure HOTP in the KeePass 2 style, set the following strings:
329 • "HmacOtp-Counter" - Counting value in decimal, starts on 0 by
331 default and increments when "hmac_otp" is called
332 • "HmacOtp-Secret" - Text string secret, OR
334 • "HmacOtp-Secret-Hex" - Hexidecimal-encoded secret, OR
336 • "HmacOtp-Secret-Base32" - Base32-encoded secret (most common), OR
338 • "HmacOtp-Secret-Base64" - Base64-encoded secret
340 NOTE: The multiple "Secret" strings are simply a way to store a secret
342 in different formats. Only one of these should actually be set or an
343 error will be thrown.
344 Here's a basic example:
346 $entry->string(otp => 'otpauth://totp/Issuer:user?secret=NBSWY3DP&issuer=Issuer');
348 # OR
349 $entry->string('TimeOtp-Secret-Base32' => 'NBSWY3DP');
350 my $otp = $entry->time_otp;
352
354 foreground_color
355 Text color represented as a string of the form "#000000".
356 background_color
358 Background color represented as a string of the form "#FFFFFF".
359 override_url
361 TODO
362 auto_type_enabled
364 Whether or not the entry is eligible to be matched for auto-typing.
365 auto_type_obfuscation
367 Whether or not to use some kind of obfuscation when sending keystroke
368 sequences to applications.
369 auto_type_default_sequence
371 The default auto-type keystroke sequence.
372 auto_type_associations
374 An array of window title / keystroke sequence associations.
375 {
377 window => 'Example Window Title',
378 keystroke_sequence => '{USERNAME}{TAB}{PASSWORD}{ENTER}',
379 }
380 Keystroke sequences can have "Placeholders", most commonly "{USERNAME}"
382 and "{PASSWORD}".
383 quality_check
385 Boolean indicating whether the entry password should be tested for
386 weakness and show up in reports.
387 strings
389 Hash with entry strings, including the standard strings as well as any
390 custom ones.
391 {
393 # Every entry has these five strings:
394 Title => { value => 'Example Entry' },
395 UserName => { value => 'jdoe' },
396 Password => { value => 's3cr3t', protect => true },
397 URL => { value => 'https://example.com' }
398 Notes => { value => '' },
399 # May also have custom strings:
400 MySystem => { value => 'The mainframe' },
401 }
402 There are methods available to provide more convenient access to
404 strings, including "string", "string_value", "expand_string_value" and
405 "string_peek".
406 binaries
408 Files or attachments. Binaries are similar to strings except they have
409 a value of bytes instead of test characters.
410 {
412 'myfile.txt' => {
413 value => '...',
414 },
415 'mysecrets.txt' => {
416 value => '...',
417 protect => true,
418 },
419 }
420 There are methods available to provide more convenient access to
422 binaries, including "binary" and "binary_value".
423 history
425 Array of historical entries. Historical entries are prior versions of
426 the same entry so they all share the same UUID with the current entry.
427 notes
429 Alias for the Notes string value.
430 password
432 Alias for the Password string value.
433 title
435 Alias for the Title string value.
436 url
438 Alias for the URL string value.
439 username
441 Aliases for the UserName string value.
442
444 string
445 \%string = $entry->string($string_key);
446 $entry->string($string_key, \%string);
448 $entry->string($string_key, %attributes);
449 $entry->string($string_key, $value); # same as: value => $value
450 Get or set a string. Every string has a unique (to the entry) key and
452 flags and so are returned as a hash structure. For example:
453 $string = {
455 value => 'Password',
456 protect => true, # optional
457 };
458 Every string should have a value (but might be "undef" due to memory
460 protection) and these optional flags which might exist:
461 • "protect" - Whether or not the string value should be memory-
463 protected.
464 string_value
466 $string = $entry->string_value($string_key);
467 Access a string value directly. The arguments are the same as for
469 "string". Returns "undef" if the string is not set or is currently
470 memory-protected. This is just a shortcut for:
471 my $string = do {
473 my $s = $entry->string(...);
474 defined $s ? $s->{value} : undef;
475 };
476 expand_string_value
478 $string = $entry->expand_string_value($string_key);
479 Same as "string_value" but will substitute placeholders and resolve
481 field references. Any placeholders that do not expand to values are
482 left as-is.
483 See "Placeholders".
485 Some placeholders (notably field references) require the entry be
487 connected to a database and will throw an error if it is not.
488 expand_notes
490 Shortcut equivalent to "->expand_string_value('Notes')".
491 expand_password
493 Shortcut equivalent to "->expand_string_value('Password')".
494 expand_title
496 Shortcut equivalent to "->expand_string_value('Title')".
497 expand_url
499 Shortcut equivalent to "->expand_string_value('URL')".
500 expand_username
502 Shortcut equivalent to "->expand_string_value('UserName')".
503 other_strings
505 $other = $entry->other_strings;
506 $other = $entry->other_strings($delimiter);
507 Get a concatenation of all non-standard string values. The default
509 delimiter is a newline. This is is useful for executing queries to
510 search for entities based on the contents of these other strings (if
511 any).
512 string_peek
514 $string = $entry->string_peek($string_key);
515 Same as "string_value" but can also retrieve the value from protected-
517 memory if the value is currently protected.
518 add_auto_type_association
520 $entry->add_auto_type_association(\%association);
521 Add a new auto-type association to an entry.
523 expand_keystroke_sequence
525 $string = $entry->expand_keystroke_sequence($keystroke_sequence);
526 $string = $entry->expand_keystroke_sequence(\%association);
527 $string = $entry->expand_keystroke_sequence; # use default auto-type sequence
528 Get a keystroke sequence after placeholder expansion.
530 binary
532 \%binary = $entry->binary($binary_key);
533 $entry->binary($binary_key, \%binary);
535 $entry->binary($binary_key, %attributes);
536 $entry->binary($binary_key, $value); # same as: value => $value
537 Get or set a binary. Every binary has a unique (to the entry) key and
539 flags and so are returned as a hash structure. For example:
540 $binary = {
542 value => '...',
543 protect => true, # optional
544 };
545 Every binary should have a value (but might be "undef" due to memory
547 protection) and these optional flags which might exist:
548 • "protect" - Whether or not the binary value should be memory-
550 protected.
551 binary_value
553 $binary = $entry->binary_value($binary_key);
554 Access a binary value directly. The arguments are the same as for
556 "binary". Returns "undef" if the binary is not set or is currently
557 memory-protected. This is just a shortcut for:
558 my $binary = do {
560 my $b = $entry->binary(...);
561 defined $b ? $b->{value} : undef;
562 };
563 hmac_otp
565 $otp = $entry->hmac_otp(%options);
566 Generate an HMAC-based one-time password, or "undef" if HOTP is not
568 configured for the entry. The entry's strings generally must first be
569 unprotected, just like when accessing the password. Valid options are:
570 • "counter" - Specify the counter value
572 To configure HOTP, see "One-time Passwords".
574 time_otp
576 $otp = $entry->time_otp(%options);
577 Generate a time-based one-time password, or "undef" if TOTP is not
579 configured for the entry. The entry's strings generally must first be
580 unprotected, just like when accessing the password. Valid options are:
581 • "now" - Specify the value for determining the time-step counter
583 To configure TOTP, see "One-time Passwords".
585 hmac_otp_uri
587 time_otp_uri
588 $uri_string = $entry->hmac_otp_uri;
589 $uri_string = $entry->time_otp_uri;
590 Get a HOTP or TOTP otpauth URI for the entry, if available.
592 To configure OTP, see "One-time Passwords".
594 size
596 $size = $entry->size;
597 Get the size (in bytes) of an entry.
599 NOTE: This is not an exact figure because there is no canonical
601 serialization of an entry. This size should only be used as a rough
602 estimate for comparison with other entries or to impose data size
603 limitations.
604 history_size
606 $size = $entry->history_size;
607 Get the size (in bytes) of all historical entries combined.
609 prune_history
611 @removed_historical_entries = $entry->prune_history(%options);
612 Remove just as many older historical entries as necessary to get under
614 the database limits. The limits are taken from the connected database
615 (if any) or can be overridden with %options:
616 • "max_items" - Maximum number of historical entries to keep
618 (default: 10, no limit: -1)
619 • "max_size" - Maximum total size (in bytes) of historical entries to
621 keep (default: 6 MiB, no limit: -1)
622 • "max_age" - Maximum age (in days) of historical entries to keep
624 (default: 365, no limit: -1)
625 add_historical_entry
627 $entry->add_historical_entry($entry);
628 Add an entry to the history.
630 remove_historical_entry
632 $entry->remove_historical_entry($historical_entry);
633 Remove an entry from the history.
635 current_entry
637 $current_entry = $entry->current_entry;
638 Get an entry's current entry. If the entry itself is current (not
640 historical), itself is returned.
641 is_current
643 $bool = $entry->is_current;
644 Get whether or not an entry is considered current (i.e. not
646 historical). An entry is current if it is directly in the parent
647 group's entry list.
648 is_historical
650 $bool = $entry->is_historical;
651 Get whether or not an entry is considered historical (i.e. not
653 current).
654 This is just the inverse of "is_current".
656 remove
658 $entry = $entry->remove;
659 Remove an entry from its parent group. If the entry is historical,
661 remove it from the history of the current entry. If the entry is
662 current, this behaves the same as "remove" in File::KDBX::Object.
663 searching_enabled
665 $bool = $entry->searching_enabled;
666 Get whether or not an entry may show up in search results. This is
668 determine from the entry's parent group's "effective_enable_searching"
669 in File::KDBX::Group value.
670 Throws if entry has no parent group or if the entry is not connected to
672 a database.
673
675 Please report any bugs or feature requests on the bugtracker website
676 <https://github.com/chazmcgarvey/File-KDBX/issues>
677 When submitting a bug or request, please include a test-file or a patch
679 to an existing test-file that illustrates the bug or desired feature.
680
682 Charles McGarvey <ccm@cpan.org>
683
685 This software is copyright (c) 2022 by Charles McGarvey.
686 This is free software; you can redistribute it and/or modify it under
688 the same terms as the Perl 5 programming language system itself.
689perl v5.36.1 2023-09-27 File::KDBX::Entry(3)