1 package File
::KDBX
::Object
;
2 # ABSTRACT: A KDBX database object
7 use Devel
::GlobalDestruction
;
8 use File
::KDBX
::Constants
qw(:bool);
10 use File
::KDBX
::Util
qw(:uuid);
11 use Hash
::Util
::FieldHash
qw(fieldhashes);
12 use List
::Util
qw(any first);
13 use Ref
::Util
qw(is_arrayref is_plain_arrayref is_plain_hashref is_ref);
14 use Scalar
::Util
qw(blessed weaken);
17 our $VERSION = '999.999'; # VERSION
19 fieldhashes \
my (%KDBX, %PARENT, %TXNS, %REFS, %SIGNALS);
23 $object = File
::KDBX
::Object-
>new;
24 $object = File
::KDBX
::Object-
>new(%attributes);
25 $object = File
::KDBX
::Object-
>new(\
%data);
26 $object = File
::KDBX
::Object-
>new(\
%data, $kdbx);
28 Construct a new KDBX object
.
30 There
is a subtlety to
take note of
. There
is a significant difference between
:
32 File
::KDBX
::Entry-
>new(username
=> 'iambatman');
36 File
::KDBX
::Entry-
>new({username
=> 'iambatman'}); # WRONG
38 In the first
, an empty object
is first created
and then initialized with whatever I
<attributes
> are
given. In
39 the second
, a hashref
is blessed
and essentially becomes the object
. The significance
is that the hashref
40 key-value pairs will remain as-is so the structure
is expected to adhere to the shape of a raw B
<Object
>
41 (which varies based on the type of object
), whereas with the first the attributes will set the structure
in
42 the correct way
(just like using the object accessors
/ getters / setters
).
44 The second example isn
't I<generally> wrong -- this type of construction is supported for a reason, to allow
45 for working with KDBX objects at a low level -- but it is wrong in this specific case only because
46 C<< {username => $str} >> isn't a valid raw KDBX entry object
. The L
</username
> attribute
is really a proxy
47 for the C
<UserName
> string
, so the equivalent raw entry object should be
48 C
<< {strings
=> {UserName
=> {value
=> $str}}} >>. These are roughly equivalent
:
50 File
::KDBX
::Entry-
>new(username
=> 'iambatman');
51 File
::KDBX
::Entry-
>new({strings
=> {UserName
=> {value
=> 'iambatman'}}});
53 If this explanation went over your head
, that
's fine. Just stick with the attributes since they are typically
54 easier to use correctly and provide the most convenience. If in the future you think of some kind of KDBX
55 object manipulation you want to do that isn't supported by the accessors
and methods
, just know you I
<can
>
56 access an object
's data directly.
64 return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
67 $data = shift if is_plain_hashref($_[0]);
70 $kdbx = shift if @_ % 2 == 1;
73 $args{kdbx} //= $kdbx if defined $kdbx;
75 my $self = bless $data // {}, $class;
77 $self->_set_nonlazy_attributes if !$data;
81 sub _set_nonlazy_attributes { die 'Not implemented
' }
85 $object = $object->init(%attributes);
87 Called by the constructor to set attributes. You normally should not call this.
95 while (my ($key, $val) = each %args) {
96 if (my $method = $self->can($key)) {
106 $object = File::KDBX::Object->wrap($object);
108 Ensure that a KDBX object is blessed.
115 return $object if blessed $object && $object->isa($class);
116 return $class->new(@_, @$object) if is_arrayref($object);
117 return $class->new($object, @_);
122 $label = $object->label;
123 $object->label($label);
125 Get or set the object's label
, a text string that can act as a non-unique identifier
. For an entry
, the label
126 is its title string
. For a group
, the label
is its name
.
130 sub label
{ die 'Not implemented' }
134 $object_copy = $object->clone(%options);
135 $object_copy = File
::KDBX
::Object-
>new($object);
137 Make a clone of an object
. By
default the clone
is indeed an exact copy that
is connected to the same database
138 but
not actually included
in the object tree
(i
.e
. it
has no parent group
). Some options are allowed to get
142 * C<new_uuid> - If set, generate a new UUID for the copy (default: false)
143 * C<parent> - If set, add the copy to the same parent group, if any (default: false)
144 * C<relabel> - If set, append " - Copy" to the object's title or name (default: false)
145 * C<entries> - If set, copy child entries, if any (default: true)
146 * C<groups> - If set, copy child groups, if any (default: true)
147 * C<history> - If set, copy entry history, if any (default: true)
148 * C<reference_password> - Toggle whether or not cloned entry's Password string should be set as a field
149 reference to the original entry's Password string (default: false)
150 * C<reference_username> - Toggle whether or not cloned entry's UserName string should be set as a field
151 reference to the original entry's UserName string (default: false)
155 my %CLONE = (entries
=> 1, groups
=> 1, history
=> 1);
160 local $CLONE{new_uuid
} = $args{new_uuid
} // $args{parent
} // 0;
161 local $CLONE{entries
} = $args{entries
} // 1;
162 local $CLONE{groups
} = $args{groups
} // 1;
163 local $CLONE{history
} = $args{history
} // 1;
164 local $CLONE{reference_password
} = $args{reference_password
} // 0;
165 local $CLONE{reference_username
} = $args{reference_username
} // 0;
168 my $copy = Storable
::dclone
($self);
170 if ($args{relabel
} and my $label = $self->label) {
171 $copy->label("$label - Copy");
173 if ($args{parent
} and my $parent = $self->group) {
174 $parent->add_object($copy);
180 sub STORABLE_freeze
{
185 delete $copy->{entries
} if !$CLONE{entries
};
186 delete $copy->{groups
} if !$CLONE{groups
};
187 delete $copy->{history
} if !$CLONE{history
};
189 return ($cloning ? Hash
::Util
::FieldHash
::id
($self) : ''), $copy;
198 @$self{keys %$copy} = values %$copy;
201 my $kdbx = $KDBX{$addr};
202 $self->kdbx($kdbx) if $kdbx;
205 if (defined $self->{uuid
}) {
206 if (($CLONE{reference_password
} || $CLONE{reference_username
}) && $self->can('strings')) {
207 my $uuid = format_uuid
($self->{uuid
});
209 local $CLONE{new_uuid
} = 0;
210 local $CLONE{entries
} = 1;
211 local $CLONE{groups
} = 1;
212 local $CLONE{history
} = 1;
213 local $CLONE{reference_password
} = 0;
214 local $CLONE{reference_username
} = 0;
215 # Clone only the entry's data and manually bless to avoid infinite recursion.
216 bless Storable
::dclone
({%$copy}), 'File::KDBX::Entry';
218 my $txn = $self->begin_work(snapshot
=> $clone_obj);
219 if ($CLONE{reference_password
}) {
220 $self->password("{REF:P\@I:$uuid}");
222 if ($CLONE{reference_username
}) {
223 $self->username("{REF:U\@I:$uuid}");
227 $self->uuid(generate_uuid
) if $CLONE{new_uuid
};
230 # Dualvars aren't cloned as dualvars, so dualify the icon.
231 $self->icon_id($self->{icon_id
}) if defined $self->{icon_id
};
236 $kdbx = $object->kdbx;
237 $object->kdbx($kdbx);
239 Get
or set the L
<File
::KDBX
> instance connected with this object
. Throws
if the object
is disconnected
. Other
240 object methods might only work
if the object
is connected to a database
and so they might also throw
if the
241 object
is disconnected
. If you
're not sure if an object is connected, try L</is_connected>.
247 $self = $self->new if !ref $self;
249 if (my $kdbx = shift) {
250 $KDBX{$self} = $kdbx;
257 $KDBX{$self} or throw 'Object
is disconnected
', object => $self;
262 $bool = $object->is_connected;
264 Determine whether or not an object is connected to a database.
270 return !!eval { $self->kdbx };
275 $string_uuid = $object->id;
276 $string_uuid = $object->id($delimiter);
278 Get the unique identifier for this object as a B<formatted> UUID string, typically for display purposes. You
279 could use this to compare with other identifiers formatted with the same delimiter, but it is more efficient
280 to use the raw UUID for that purpose (see L</uuid>).
282 A delimiter can optionally be provided to break up the UUID string visually. See
283 L<File::KDBX::Util/format_uuid>.
287 sub id { format_uuid(shift->uuid, @_) }
291 $parent_group = $object->group;
292 $object->group($parent_group);
294 Get or set the parent group to which an object belongs or C<undef> if it belongs to no group.
301 if (my $new_group = shift) {
302 my $old_group = $self->group;
303 return $new_group if Hash::Util::FieldHash::id($old_group) == Hash::Util::FieldHash::id($new_group);
304 # move to a new parent
305 $self->remove(signal => 0) if $old_group;
306 $self->location_changed('now
');
307 $new_group->add_object($self);
310 my $id = Hash::Util::FieldHash::id($self);
311 if (my $group = $PARENT{$self}) {
312 my $method = $self->_parent_container;
313 return $group if first { $id == Hash::Util::FieldHash::id($_) } @{$group->$method};
314 delete $PARENT{$self};
316 # always get lineage from root to leaf because the other way requires parent, so it would be recursive
317 my $lineage = $self->kdbx->_trace_lineage($self) or return;
318 my $group = pop @$lineage or return;
319 $PARENT{$self} = $group; weaken $PARENT{$self};
325 if (my $parent = shift) {
326 $PARENT{$self} = $parent;
327 weaken $PARENT{$self};
330 delete $PARENT{$self};
335 ### Name of the parent attribute expected to contain the object
336 sub _parent_container { die 'Not implemented
' }
340 \@lineage = $object->lineage;
341 \@lineage = $object->lineage($base_group);
343 Get the direct line of ancestors from C<$base_group> (default: the root group) to an object. The lineage
344 includes the base group but I<not> the target object. Returns C<undef> if the target is not in the database
345 structure. Returns an empty arrayref is the object itself is a root group.
353 my $base_addr = $base ? Hash::Util::FieldHash::id($base) : 0;
358 while ($object = $object->group) {
359 unshift @path, $object;
360 last if $base_addr == Hash::Util::FieldHash::id($object);
362 return \@path if @path && ($base_addr == Hash::Util::FieldHash::id($path[0]) || $path[0]->is_root);
365 return $self->kdbx->_trace_lineage($self, $base);
370 $object = $object->remove(%options);
372 Remove an object from its parent. If the object is a group, all contained objects stay with the object and so
373 are removed as well, just like cutting off a branch takes the leafs as well. Options:
376 * C<signal> Whether or not to signal the removal to the connected database (default: true)
382 my $parent = $self->group;
383 $parent->remove_object($self, @_) if $parent;
384 $self->_set_group(undef);
390 $object = $object->recycle;
392 Remove an object from its parent and add it to the connected database's recycle bin group
.
398 return $self->group($self->kdbx->recycle_bin);
401 =method recycle_or_remove
403 $object = $object->recycle_or_remove;
405 Recycle
or remove an object
, depending on the connected database
's L<File::KDBX/recycle_bin_enabled>. If the
406 object is not connected to a database or is already in the recycle bin, remove it.
410 sub recycle_or_remove {
412 my $kdbx = eval { $self->kdbx };
413 if ($kdbx && $kdbx->recycle_bin_enabled && !$self->is_recycled) {
423 $bool = $object->is_recycled;
425 Get whether or not an object is in a recycle bin.
431 eval { $self->kdbx } or return FALSE;
432 return !!($self->group && any { $_->is_recycle_bin } @{$self->lineage});
435 ##############################################################################
439 @tags = $entry->tag_list;
441 Get a list of tags, split from L</tag> using delimiters C<,>, C<.>, C<:>, C<;> and whitespace.
447 return grep { $_ ne '' } split(/[,\.:;]|\s+/, trim($self->tags) // '');
452 $image_data = $object->custom_icon;
453 $image_data = $object->custom_icon($image_data, %attributes);
455 Get or set an icon image. Returns C<undef> if there is no custom icon set. Setting a custom icon will change
456 the L</custom_icon_uuid> attribute.
458 Custom icon attributes (supported in KDBX4.1 and greater):
461 * C<name> - Name of the icon (text)
462 * C<last_modification_time> - Just what it says (datetime)
468 my $kdbx = $self->kdbx;
471 my $uuid = defined $img ? $kdbx->add_custom_icon($img, @_) : undef;
472 $self->icon_id(0) if $uuid;
473 $self->custom_icon_uuid($uuid);
476 return $kdbx->custom_icon_data($self->custom_icon_uuid);
481 \%all_data = $object->custom_data;
482 $object->custom_data(\%all_data);
484 \%data = $object->custom_data($key);
485 $object->custom_data($key => \%data);
486 $object->custom_data(%data);
487 $object->custom_data(key => $value, %data);
489 Get and set custom data. Custom data is metadata associated with an object. It is a set of key-value pairs
490 used to store arbitrary data, usually used by software like plug-ins to keep track of state rather than by end
493 Each data item can have a few attributes associated with it.
496 * C<key> - A unique text string identifier used to look up the data item (required)
497 * C<value> - A text string value (required)
498 * C<last_modification_time> (optional, KDBX4.1+)
504 $self->{custom_data} = shift if @_ == 1 && is_plain_hashref($_[0]);
505 return $self->{custom_data} //= {} if !@_;
507 my %args = @_ == 2 ? (key => shift, value => shift)
508 : @_ % 2 == 1 ? (key => shift, @_) : @_;
510 if (!$args{key} && !$args{value}) {
511 my %standard = (key => 1, value => 1, last_modification_time => 1);
512 my @other_keys = grep { !$standard{$_} } keys %args;
513 if (@other_keys == 1) {
514 my $key = $args{key} = $other_keys[0];
515 $args{value} = delete $args{$key};
519 my $key = $args{key} or throw 'Must provide a custom_data key to access
';
521 return $self->{custom_data}{$key} = $args{value} if is_plain_hashref($args{value});
523 while (my ($field, $value) = each %args) {
524 $self->{custom_data}{$key}{$field} = $value;
526 return $self->{custom_data}{$key};
529 =method custom_data_value
531 $value = $object->custom_data_value($key);
533 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
534 attributes
. This
is a shortcut
for:
536 my $data = $object->custom_data($key);
537 my $value = defined $data ? $data->{value
} : undef;
541 sub custom_data_value
{
543 my $data = $self->custom_data(@_) // return undef;
544 return $data->{value
};
547 ##############################################################################
551 $txn = $object->begin_work(%options);
552 $object->begin_work(%options);
554 Begin a new transaction
. Returns a L
<File
::KDBX
::Transaction
> object that can be scoped to ensure a rollback
555 occurs
if exceptions are thrown
. Alternatively
, if called
in void context
, there will be
no
556 B
<File
::KDBX
::Transaction
> and it
is instead your responsibility to call L
</commit> or L</rollback
> as
557 appropriate
. It
is undefined behavior to call these
if a B
<File
::KDBX
::Transaction
> exists. Recursive
558 transactions are allowed
.
560 Signals created during a transaction are delayed
until all transactions are resolved
. If the outermost
561 transaction
is committed
, then the signals are de-duplicated
and delivered
. Otherwise the signals are dropped
.
562 This means that the KDBX database will
not fix broken references
or mark itself dirty
until after the
563 transaction
is committed
.
565 How it works
: With the beginning of a transaction
, a snapshot of the object
is created
. In the event of
566 a rollback
, the object
's data is replaced with data from the snapshot.
568 By default, the snapshot is shallow (i.e. does not include subroups, entries or historical entries). This
569 means that only modifications to the object itself (its data, fields, strings, etc.) are atomic; modifications
570 to subroups etc., including adding or removing items, are auto-committed instantly and will persist regardless
571 of the result of the pending transaction. You can override this for groups, entries and history independently
575 * C<entries> - If set, snapshot entries within a group, deeply (default: false)
576 * C<groups> - If set, snapshot subroups within a group, deeply (default: false)
577 * C<history> - If set, snapshot historical entries within an entry (default: false)
579 For example, if you begin a transaction on a group object using the C<entries> option, like this:
581 $group->begin_work(entries => 1);
583 Then if you modify any of the group's entries OR add new entries OR
delete entries
, all of that will be undone
584 if the transaction
is rolled back
. With a default-configured transaction
, however
, changes to entries are kept
585 even
if the transaction
is rolled back
.
592 if (defined wantarray) {
593 require File
::KDBX
::Transaction
;
594 return File
::KDBX
::Transaction-
>new($self, @_);
598 my $orig = $args{snapshot
} // do {
599 my $c = $self->clone(
600 entries
=> $args{entries
} // 0,
601 groups
=> $args{groups
} // 0,
602 history
=> $args{history
} // 0,
604 $c->{entries
} = $self->{entries
} if !$args{entries
};
605 $c->{groups
} = $self->{groups
} if !$args{groups
};
606 $c->{history
} = $self->{history
} if !$args{history
};
610 my $id = Hash
::Util
::FieldHash
::id
($orig);
611 _save_references
($id, $self, $orig);
613 $self->_signal_begin_work;
615 push @{$self->_txns}, $orig;
622 Commit a transaction
, making updates to C
<$object> permanent
. Returns itself to allow
method chaining
.
628 my $orig = pop @{$self->_txns} or return $self;
629 $self->_commit($orig);
630 my $signals = $self->_signal_commit;
631 $self->_signal_send($signals) if !$self->_in_txn;
639 Roll back the most recent transaction
, throwing away any updates to the L
</object
> made since the transaction
640 began
. Returns itself to allow
method chaining
.
647 my $orig = pop @{$self->_txns} or return $self;
649 my $id = Hash
::Util
::FieldHash
::id
($orig);
650 _restore_references
($id, $orig);
652 $self->_signal_rollback;
657 # Get whether or not there is at least one pending transaction.
658 sub _in_txn
{ scalar @{$_[0]->_txns} }
660 # Get an array ref of pending transactions.
661 sub _txns
{ $TXNS{$_[0]} //= [] }
663 # The _commit hook notifies subclasses that a commit has occurred.
664 sub _commit
{ die 'Not implemented' }
666 # Get a reference to an object that represents an object's committed state. If there is no pending
667 # transaction, this is just $self. If there is a transaction, this is the snapshot take before the transaction
668 # began. This method is private because it provides direct access to the actual snapshot. It is important that
669 # the snapshot not be changed or a rollback would roll back to an altered state.
670 # This is used by File::KDBX::Dumper::XML so as to not dump uncommitted changes.
673 my ($orig) = @{$self->_txns};
674 return $orig // $self;
677 # In addition to cloning an object when beginning work, we also keep track its hashrefs and arrayrefs
678 # internally so that we can restore to the very same structures in the case of a rollback.
679 sub _save_references
{
684 if (is_plain_arrayref
($orig)) {
685 for (my $i = 0; $i < @$orig; ++$i) {
686 _save_references
($id, $self->[$i], $orig->[$i]);
688 $REFS{$id}{Hash
::Util
::FieldHash
::id
($orig)} = $self;
690 elsif (is_plain_hashref
($orig) || (blessed
$orig && $orig->isa(__PACKAGE__
))) {
691 for my $key (keys %$orig) {
692 _save_references
($id, $self->{$key}, $orig->{$key});
694 $REFS{$id}{Hash
::Util
::FieldHash
::id
($orig)} = $self;
698 # During a rollback, copy data from the snapshot back into the original internal structures.
699 sub _restore_references
{
701 my $orig = shift // return;
702 my $self = delete $REFS{$id}{Hash
::Util
::FieldHash
::id
($orig) // ''} // return $orig;
704 if (is_plain_arrayref
($orig)) {
705 @$self = map { _restore_references
($id, $_) } @$orig;
707 elsif (is_plain_hashref
($orig) || (blessed
$orig && $orig->isa(__PACKAGE__
))) {
708 for my $key (keys %$orig) {
709 # next if is_ref($orig->{$key}) &&
710 # (Hash::Util::FieldHash::id($self->{$key}) // 0) == Hash::Util::FieldHash::id($orig->{$key});
711 $self->{$key} = _restore_references
($id, $orig->{$key});
718 ##############################################################################
724 if ($self->_in_txn) {
725 my $stack = $self->_signal_stack;
726 my $queue = $stack->[-1];
727 push @$queue, [$type, @_];
730 $self->_signal_send([[$type, @_]]);
735 sub _signal_stack
{ $SIGNALS{$_[0]} //= [] }
737 sub _signal_begin_work
{
739 push @{$self->_signal_stack}, [];
744 my $signals = pop @{$self->_signal_stack};
745 my $previous = $self->_signal_stack->[-1] // [];
746 push @$previous, @$signals;
750 sub _signal_rollback
{
752 pop @{$self->_signal_stack};
757 my $signals = shift // [];
759 my $kdbx = $KDBX{$self} or return;
761 # de-duplicate, keeping the most recent signal for each type
763 my @signals = grep { !$seen{$_->[0]}++ } reverse @$signals;
765 for my $sig (reverse @signals) {
766 $kdbx->_handle_signal($self, @$sig);
770 ##############################################################################
775 require File
::KDBX
::Group
;
776 return File
::KDBX
::Group-
>wrap($group, $KDBX{$self});
782 require File
::KDBX
::Entry
;
783 return File
::KDBX
::Entry-
>wrap($entry, $KDBX{$self});
786 sub TO_JSON
{ +{%{$_[0]}} }
791 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
795 KDBX is an object database. This abstract class represents an object. You should not use this class directly
796 but instead use its subclasses:
799 * L<File::KDBX::Entry>
800 * L<File::KDBX::Group>
802 There is some functionality shared by both types of objects, and that's what this class provides.
804 Each object can be connected with a L<File::KDBX> database or be disconnected. A disconnected object exists in
805 memory but will not be persisted when dumping a database. It is also possible for an object to be connected
806 with a database but not be part of the object tree (i.e. is not the root group or any subroup or entry).
807 A disconnected object or an object not part of the object tree of a database can be added to a database using
811 * L<File::KDBX/add_entry>
812 * L<File::KDBX/add_group>
813 * L<File::KDBX::Group/add_entry>
814 * L<File::KDBX::Group/add_group>
815 * L<File::KDBX::Entry/add_historical_entry>
817 It is possible to copy or move objects between databases, but B<DO NOT> include the same object in more
818 than one database at once or there could be some strange aliasing effects (i.e. changes in one database might
819 effect another in unexpected ways). This could lead to difficult-to-debug problems. It is similarly not safe
820 or valid to add the same object multiple times to the same database. For example:
822 my $entry = File::KDBX::Entry->(title => 'Whatever');
825 $kdbx->add_entry($entry);
826 $another_kdbx->add_entry($entry);
829 $kdbx->add_entry($entry);
830 $kdbx->add_entry($entry); # again
834 # Copy an entry to multiple databases:
835 $kdbx->add_entry($entry);
836 $another_kdbx->add_entry($entry->clone);
838 # OR move an existing entry from one database to another:
839 $another_kdbx->add_entry($entry->remove);
843 128-bit UUID identifying the object within the connected database.
847 Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
849 =attr custom_icon_uuid
851 128-bit UUID identifying a custom icon within the connected database.
855 Text string with arbitrary tags which can be used to build a taxonomy.
857 =attr previous_parent_group
859 128-bit UUID identifying a group within the connected database the previously contained the object.
861 =attr last_modification_time
863 Date and time when the entry was last modified.
867 Date and time when the entry was created.
869 =attr last_access_time
871 Date and time when the entry was last accessed.
875 Date and time when the entry expired or will expire.
879 Boolean value indicating whether or not an entry is expired.
883 The number of times an entry has been used, which typically means how many times the B<Password> string has
886 =attr location_changed
888 Date and time when the entry was last moved to a different parent group.