1File::KDBX::Entry(3) User Contributed Perl Documentation File::KDBX::Entry(3)
2
3
4
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
17 • Title
18
19 • UserName
20
21 • Password
22
23 • URL
24
25 • Notes
26
27 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
30 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
35 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
38 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
47 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
51 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
55 Entry Placeholders
56
57 • ☑ "{TITLE}" - Title string
58
59 • ☑ "{USERNAME}" - UserName string
60
61 • ☑ "{PASSWORD}" - Password string
62
63 • ☑ "{NOTES}" - Notes string
64
65 • ☑ "{URL}" - URL string
66
67 • ☑ "{URL:SCM}" / "{URL:SCHEME}"
68
69 • ☑ "{URL:USERINFO}"
70
71 • ☑ "{URL:USERNAME}"
72
73 • ☑ "{URL:PASSWORD}"
74
75 • ☑ "{URL:HOST}"
76
77 • ☑ "{URL:PORT}"
78
79 • ☑ "{URL:PATH}"
80
81 • ☑ "{URL:QUERY}"
82
83 • ☑ "{URL:FRAGMENT}" / "{URL:HASH}"
84
85 • ☑ "{URL:RMVSCM}" / "{URL:WITHOUTSCHEME}"
86
87 • ☑ "{S:Name}" - Custom string where "Name" is the name or key of the
88 string
89
90 • ☑ "{UUID}" - Identifier (32 hexidecimal characters)
91
92 • ☑ "{HMACOTP}" - Generate an HMAC-based one-time password (its
93 counter will be incremented)
94
95 • ☑ "{TIMEOTP}" - Generate a time-based one-time password
96
97 • ☑ "{GROUP_NOTES}" - Notes of the parent group
98
99 • ☑ "{GROUP_PATH}" - Full path of the parent group
100
101 • ☑ "{GROUP}" - Name of the parent group
102
103 Field References
104
105 • ☑ "{REF:Wanted@SearchIn:Text}" - See "resolve_reference" in
106 File::KDBX
107
108 File path Placeholders
109
110 • ☑ "{APPDIR}" - Program directory path
111
112 • ☑ "{FIREFOX}" - Path to the Firefox browser executable
113
114 • ☑ "{GOOGLECHROME}" - Path to the Chrome browser executable
115
116 • ☑ "{INTERNETEXPLORER}" - Path to the Firefox browser executable
117
118 • ☑ "{OPERA}" - Path to the Opera browser executable
119
120 • ☑ "{SAFARI}" - Path to the Safari browser executable
121
122 • ☒ "{DB_PATH}" - Full file path of the database
123
124 • ☒ "{DB_DIR}" - Directory path of the database
125
126 • ☒ "{DB_NAME}" - File name (including extension) of the database
127
128 • ☒ "{DB_BASENAME}" - File name (excluding extension) of the database
129
130 • ☒ "{DB_EXT}" - File name extension
131
132 • ☑ "{ENV_DIRSEP}" - Directory separator
133
134 • ☑ "{ENV_PROGRAMFILES_X86}" - One of "%ProgramFiles(x86)%" or
135 "%ProgramFiles%"
136
137 Date and Time Placeholders
138
139 • ☑ "{DT_SIMPLE}" - Current local date and time as a sortable string
140
141 • ☑ "{DT_YEAR}" - Year component of the current local date
142
143 • ☑ "{DT_MONTH}" - Month component of the current local date
144
145 • ☑ "{DT_DAY}" - Day component of the current local date
146
147 • ☑ "{DT_HOUR}" - Hour component of the current local time
148
149 • ☑ "{DT_MINUTE}" - Minute component of the current local time
150
151 • ☑ "{DT_SECOND}" - Second component of the current local time
152
153 • ☑ "{DT_UTC_SIMPLE}" - Current UTC date and time as a sortable
154 string
155
156 • ☑ "{DT_UTC_YEAR}" - Year component of the current UTC date
157
158 • ☑ "{DT_UTC_MONTH}" - Month component of the current UTC date
159
160 • ☑ "{DT_UTC_DAY}" - Day component of the current UTC date
161
162 • ☑ "{DT_UTC_HOUR}" - Hour component of the current UTC time
163
164 • ☑ "{DT_UTC_MINUTE}" Minute Year component of the current UTC time
165
166 • ☑ "{DT_UTC_SECOND}" - Second component of the current UTC time
167
168 If the current date and time is "2012-07-25 17:05:34", the "simple"
169 form would be 20120725170534.
170
171 Special Key Placeholders
172
173 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
179 "{TAB}", "{ENTER}", "{UP}", "{DOWN}", "{LEFT}", "{RIGHT}", "{HOME}",
180 "{END}", "{PGUP}", "{PGDN}", "{INSERT}", "{DELETE}", "{SPACE}"
181
182 "{BACKSPACE}", "{BREAK}", "{CAPSLOCK}", "{ESC}", "{WIN}", "{LWIN}",
183 "{RWIN}", "{APPS}", "{HELP}", "{NUMLOCK}", "{PRTSC}", "{SCROLLLOCK}"
184
185 "{F1}", "{F2}", "{F3}", "{F4}", "{F5}", "{F6}", "{F7}", "{F8}", "{F9}",
186 "{F10}", "{F11}", "{F12}", "{F13}", "{F14}", "{F15}", "{F16}"
187
188 "{ADD}", "{SUBTRACT}", "{MULTIPLY}", "{DIVIDE}", "{NUMPAD0}",
189 "{NUMPAD1}", "{NUMPAD2}", "{NUMPAD3}", "{NUMPAD4}", "{NUMPAD5}",
190 "{NUMPAD6}", "{NUMPAD7}", "{NUMPAD8}", "{NUMPAD9}"
191
192 Miscellaneous Placeholders
193
194 • ☒ "{BASE}"
195
196 • ☒ "{BASE:SCM}" / "{BASE:SCHEME}"
197
198 • ☒ "{BASE:USERINFO}"
199
200 • ☒ "{BASE:USERNAME}"
201
202 • ☒ "{BASE:PASSWORD}"
203
204 • ☒ "{BASE:HOST}"
205
206 • ☒ "{BASE:PORT}"
207
208 • ☒ "{BASE:PATH}"
209
210 • ☒ "{BASE:QUERY}"
211
212 • ☒ "{BASE:FRAGMENT}" / "{BASE:HASH}"
213
214 • ☒ "{BASE:RMVSCM}" / "{BASE:WITHOUTSCHEME}"
215
216 • ☒ "{CLIPBOARD-SET:/Text/}"
217
218 • ☒ "{CLIPBOARD}"
219
220 • ☒ "{CMD:/CommandLine/Options/}"
221
222 • ☑ "{C:Comment}" - Comments are simply replaced by nothing
223
224 • ☑ "{ENV:}" and "%ENV%" - Environment variables
225
226 • ☒ "{GROUP_SEL_NOTES}"
227
228 • ☒ "{GROUP_SEL_PATH}"
229
230 • ☒ "{GROUP_SEL}"
231
232 • ☒ "{NEWPASSWORD}"
233
234 • ☒ "{NEWPASSWORD:/Profile/}"
235
236 • ☒ "{PASSWORD_ENC}"
237
238 • ☒ "{PICKCHARS}"
239
240 • ☒ "{PICKCHARS:Field:Options}"
241
242 • ☒ "{PICKFIELD}"
243
244 • ☒ "{T-CONV:/Text/Type/}"
245
246 • ☒ "{T-REPLACE-RX:/Text/Type/Replace/}"
247
248 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
255 $File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER'} = sub {
256 my ($entry) = @_;
257 ...;
258 };
259
260 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
265 $File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER:'} = sub {
266 my ($entry, $arg) = @_; # ^ Notice the colon here
267 ...;
268 };
269
270 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
276 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
282 $File::KDBX::PLACEHOLDERS{'RAND'} = $File::KDBX::PLACEHOLDERS{'RAND:'} = sub {
283 (undef, my $arg) = @_;
284 return defined $arg ? rand($arg) : rand;
285 };
286
287 You can also remove placeholder handlers. If you want to disable
288 placeholder expansion entirely, just delete all the handlers:
289
290 %File::KDBX::PLACEHOLDERS = ();
291
292 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
298 • KeePass 2 <https://keepass.info/help/base/placeholders.html#otp>
299
300 • KeePassXC
301
302 NOTE: To use this feature, you must install the suggested dependency:
303
304 • Pass::OTP
305
306 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
310 To configure TOTP in the KeePass 2 style, set the following strings:
311
312 • "TimeOtp-Algorithm" - Cryptographic algorithm, one of "HMAC-SHA-1"
313 (default), "HMAC-SHA-256" and "HMAC-SHA-512"
314
315 • "TimeOtp-Length" - Number of digits each one-time password is
316 (default: 6, maximum: 8)
317
318 • "TimeOtp-Period" - Time-step size in seconds (default: 30)
319
320 • "TimeOtp-Secret" - Text string secret, OR
321
322 • "TimeOtp-Secret-Hex" - Hexidecimal-encoded secret, OR
323
324 • "TimeOtp-Secret-Base32" - Base32-encoded secret (most common), OR
325
326 • "TimeOtp-Secret-Base64" - Base64-encoded secret
327
328 To configure HOTP in the KeePass 2 style, set the following strings:
329
330 • "HmacOtp-Counter" - Counting value in decimal, starts on 0 by
331 default and increments when "hmac_otp" is called
332
333 • "HmacOtp-Secret" - Text string secret, OR
334
335 • "HmacOtp-Secret-Hex" - Hexidecimal-encoded secret, OR
336
337 • "HmacOtp-Secret-Base32" - Base32-encoded secret (most common), OR
338
339 • "HmacOtp-Secret-Base64" - Base64-encoded secret
340
341 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
345 Here's a basic example:
346
347 $entry->string(otp => 'otpauth://totp/Issuer:user?secret=NBSWY3DP&issuer=Issuer');
348 # OR
349 $entry->string('TimeOtp-Secret-Base32' => 'NBSWY3DP');
350
351 my $otp = $entry->time_otp;
352
354 foreground_color
355 Text color represented as a string of the form "#000000".
356
357 background_color
358 Background color represented as a string of the form "#FFFFFF".
359
360 override_url
361 TODO
362
363 auto_type_enabled
364 Whether or not the entry is eligible to be matched for auto-typing.
365
366 auto_type_obfuscation
367 Whether or not to use some kind of obfuscation when sending keystroke
368 sequences to applications.
369
370 auto_type_default_sequence
371 The default auto-type keystroke sequence.
372
373 auto_type_associations
374 An array of window title / keystroke sequence associations.
375
376 {
377 window => 'Example Window Title',
378 keystroke_sequence => '{USERNAME}{TAB}{PASSWORD}{ENTER}',
379 }
380
381 Keystroke sequences can have "Placeholders", most commonly "{USERNAME}"
382 and "{PASSWORD}".
383
384 quality_check
385 Boolean indicating whether the entry password should be tested for
386 weakness and show up in reports.
387
388 strings
389 Hash with entry strings, including the standard strings as well as any
390 custom ones.
391
392 {
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
403 There are methods available to provide more convenient access to
404 strings, including "string", "string_value", "expand_string_value" and
405 "string_peek".
406
407 binaries
408 Files or attachments. Binaries are similar to strings except they have
409 a value of bytes instead of test characters.
410
411 {
412 'myfile.txt' => {
413 value => '...',
414 },
415 'mysecrets.txt' => {
416 value => '...',
417 protect => true,
418 },
419 }
420
421 There are methods available to provide more convenient access to
422 binaries, including "binary" and "binary_value".
423
424 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
428 notes
429 Alias for the Notes string value.
430
431 password
432 Alias for the Password string value.
433
434 title
435 Alias for the Title string value.
436
437 url
438 Alias for the URL string value.
439
440 username
441 Aliases for the UserName string value.
442
444 string
445 \%string = $entry->string($string_key);
446
447 $entry->string($string_key, \%string);
448 $entry->string($string_key, %attributes);
449 $entry->string($string_key, $value); # same as: value => $value
450
451 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
454 $string = {
455 value => 'Password',
456 protect => true, # optional
457 };
458
459 Every string should have a value (but might be "undef" due to memory
460 protection) and these optional flags which might exist:
461
462 • "protect" - Whether or not the string value should be memory-
463 protected.
464
465 string_value
466 $string = $entry->string_value($string_key);
467
468 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
472 my $string = do {
473 my $s = $entry->string(...);
474 defined $s ? $s->{value} : undef;
475 };
476
477 expand_string_value
478 $string = $entry->expand_string_value($string_key);
479
480 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
484 See "Placeholders".
485
486 Some placeholders (notably field references) require the entry be
487 connected to a database and will throw an error if it is not.
488
489 expand_notes
490 Shortcut equivalent to "->expand_string_value('Notes')".
491
492 expand_password
493 Shortcut equivalent to "->expand_string_value('Password')".
494
495 expand_title
496 Shortcut equivalent to "->expand_string_value('Title')".
497
498 expand_url
499 Shortcut equivalent to "->expand_string_value('URL')".
500
501 expand_username
502 Shortcut equivalent to "->expand_string_value('UserName')".
503
504 other_strings
505 $other = $entry->other_strings;
506 $other = $entry->other_strings($delimiter);
507
508 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
513 string_peek
514 $string = $entry->string_peek($string_key);
515
516 Same as "string_value" but can also retrieve the value from protected-
517 memory if the value is currently protected.
518
519 add_auto_type_association
520 $entry->add_auto_type_association(\%association);
521
522 Add a new auto-type association to an entry.
523
524 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
529 Get a keystroke sequence after placeholder expansion.
530
531 binary
532 \%binary = $entry->binary($binary_key);
533
534 $entry->binary($binary_key, \%binary);
535 $entry->binary($binary_key, %attributes);
536 $entry->binary($binary_key, $value); # same as: value => $value
537
538 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
541 $binary = {
542 value => '...',
543 protect => true, # optional
544 };
545
546 Every binary should have a value (but might be "undef" due to memory
547 protection) and these optional flags which might exist:
548
549 • "protect" - Whether or not the binary value should be memory-
550 protected.
551
552 binary_value
553 $binary = $entry->binary_value($binary_key);
554
555 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
559 my $binary = do {
560 my $b = $entry->binary(...);
561 defined $b ? $b->{value} : undef;
562 };
563
564 hmac_otp
565 $otp = $entry->hmac_otp(%options);
566
567 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
571 • "counter" - Specify the counter value
572
573 To configure HOTP, see "One-time Passwords".
574
575 time_otp
576 $otp = $entry->time_otp(%options);
577
578 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
582 • "now" - Specify the value for determining the time-step counter
583
584 To configure TOTP, see "One-time Passwords".
585
586 hmac_otp_uri
587 time_otp_uri
588 $uri_string = $entry->hmac_otp_uri;
589 $uri_string = $entry->time_otp_uri;
590
591 Get a HOTP or TOTP otpauth URI for the entry, if available.
592
593 To configure OTP, see "One-time Passwords".
594
595 size
596 $size = $entry->size;
597
598 Get the size (in bytes) of an entry.
599
600 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
605 history_size
606 $size = $entry->history_size;
607
608 Get the size (in bytes) of all historical entries combined.
609
610 prune_history
611 @removed_historical_entries = $entry->prune_history(%options);
612
613 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
617 • "max_items" - Maximum number of historical entries to keep
618 (default: 10, no limit: -1)
619
620 • "max_size" - Maximum total size (in bytes) of historical entries to
621 keep (default: 6 MiB, no limit: -1)
622
623 • "max_age" - Maximum age (in days) of historical entries to keep
624 (default: 365, no limit: -1)
625
626 add_historical_entry
627 $entry->add_historical_entry($entry);
628
629 Add an entry to the history.
630
631 remove_historical_entry
632 $entry->remove_historical_entry($historical_entry);
633
634 Remove an entry from the history.
635
636 current_entry
637 $current_entry = $entry->current_entry;
638
639 Get an entry's current entry. If the entry itself is current (not
640 historical), itself is returned.
641
642 is_current
643 $bool = $entry->is_current;
644
645 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
649 is_historical
650 $bool = $entry->is_historical;
651
652 Get whether or not an entry is considered historical (i.e. not
653 current).
654
655 This is just the inverse of "is_current".
656
657 remove
658 $entry = $entry->remove;
659
660 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
664 searching_enabled
665 $bool = $entry->searching_enabled;
666
667 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
671 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
678 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
687 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.
689
690
691
692perl v5.36.1 2023-09-27 File::KDBX::Entry(3)