38class PyKeePass:
  39    """Open a KeePass database
  40
  41    Args:
  42        filename (`str`, optional): path to database or stream object.
  43            If None, the path given when the database was opened is used.
  44        password (`str`, optional): database password.  If None,
  45            database is assumed to have no password
  46        keyfile (`str`, optional): path to keyfile.  If None,
  47            database is assumed to have no keyfile
  48        transformed_key (`bytes`, optional): precomputed transformed
  49            key.
  50        decrypt (`bool`, optional): whether to decrypt XML payload.
  51            Set `False` to access outer header information without decrypting
  52            database.
  53
  54    Raises:
  55        `CredentialsError`: raised when password/keyfile or transformed key
  56            are wrong
  57        `HeaderChecksumError`: raised when checksum in database header is
  58            is wrong.  e.g. database tampering or file corruption
  59        `PayloadChecksumError`: raised when payload blocks checksum is wrong,
  60            e.g. corruption during database saving
  61
  62    """
  63
  64    # TODO: raise, no filename provided, database not open
  65
  66    def __init__(self, filename, password=None, keyfile=None,
  67                 transformed_key=None, decrypt=True):
  68
  69        self.read(
  70            filename=filename,
  71            password=password,
  72            keyfile=keyfile,
  73            transformed_key=transformed_key,
  74            decrypt=decrypt
  75        )
  76
  77    def __enter__(self):
  78        return self
  79
  80    def __exit__(self, typ, value, tb):
  81        # see issue 137
  82        pass
  83
  84    def read(self, filename=None, password=None, keyfile=None,
  85             transformed_key=None, decrypt=True):
  86        """
  87        See class docstring.
  88        """
  89
  90        # TODO: - raise, no filename provided, database not open
  91        self._password = password
  92        self._keyfile = keyfile
  93        if filename:
  94            self.filename = filename
  95        else:
  96            filename = self.filename
  97
  98        try:
  99            if hasattr(filename, "read"):
 100                self.kdbx = KDBX.parse_stream(
 101                    filename,
 102                    password=password,
 103                    keyfile=keyfile,
 104                    transformed_key=transformed_key,
 105                    decrypt=decrypt
 106                )
 107            else:
 108                self.kdbx = KDBX.parse_file(
 109                    filename,
 110                    password=password,
 111                    keyfile=keyfile,
 112                    transformed_key=transformed_key,
 113                    decrypt=decrypt
 114                )
 115
 116        except CheckError as e:
 117            if e.path == '(parsing) -> header -> sig_check':
 118                raise HeaderChecksumError("Not a KeePass database")
 119            else:
 120                raise
 121
 122        # body integrity/verification
 123        except ChecksumError as e:
 124            if e.path in (
 125                    '(parsing) -> body -> cred_check', # KDBX4
 126                    '(parsing) -> cred_check' # KDBX3
 127                    ):
 128                raise CredentialsError("Invalid credentials")
 129            elif e.path == '(parsing) -> body -> sha256':
 130                raise HeaderChecksumError("Corrupted database")
 131            elif e.path in (
 132                    '(parsing) -> body -> payload -> hmac_hash', # KDBX4
 133                    '(parsing) -> xml -> block_hash' # KDBX3
 134                    ):
 135                raise PayloadChecksumError("Error reading database contents")
 136            else:
 137                raise
 138
 139    def reload(self):
 140        """Reload current database using previously given credentials """
 141
 142        self.read(self.filename, self.password, self.keyfile)
 143
 144    def save(self, filename=None, transformed_key=None):
 145        """Save current database object to disk.
 146
 147        Args:
 148            filename (`str`, optional): path to database or stream object.
 149                If None, the path given when the database was opened is used.
 150                PyKeePass.filename is unchanged.
 151            transformed_key (`bytes`, optional): precomputed transformed
 152                key.
 153        """
 154
 155        if not filename:
 156            filename = self.filename
 157
 158        if hasattr(filename, "write"):
 159            KDBX.build_stream(
 160                self.kdbx,
 161                filename,
 162                password=self.password,
 163                keyfile=self.keyfile,
 164                transformed_key=transformed_key,
 165                decrypt=True
 166            )
 167        else:
 168            # save to temporary file to prevent database clobbering
 169            # see issues 223, 101
 170            filename_tmp = Path(filename).with_suffix('.tmp')
 171            try:
 172                KDBX.build_file(
 173                    self.kdbx,
 174                    filename_tmp,
 175                    password=self.password,
 176                    keyfile=self.keyfile,
 177                    transformed_key=transformed_key,
 178                    decrypt=True
 179                )
 180            except Exception as e:
 181                os.remove(filename_tmp)
 182                raise e
 183            shutil.move(filename_tmp, filename)
 184
 185    @property
 186    def version(self):
 187        """`tuple` of `int`: Length 2 tuple of ints containing major and minor versions.
 188        Generally (3, 1) or (4, 0)."""
 189        return (
 190            self.kdbx.header.value.major_version,
 191            self.kdbx.header.value.minor_version
 192        )
 193
 194    @property
 195    def encryption_algorithm(self):
 196        """`str`: encryption algorithm used by database during decryption.
 197        Can be one of 'aes256', 'chacha20', or 'twofish'."""
 198        return self.kdbx.header.value.dynamic_header.cipher_id.data
 199
 200    @property
 201    def kdf_algorithm(self):
 202        """`str`: key derivation algorithm used by database during decryption.
 203        Can be one of 'aeskdf', 'argon2', or 'aeskdf'"""
 204        if self.version == (3, 1):
 205            return 'aeskdf'
 206        elif self.version == (4, 0):
 207            kdf_parameters = self.kdbx.header.value.dynamic_header.kdf_parameters.data.dict
 208            if kdf_parameters['$UUID'].value == kdf_uuids['argon2']:
 209                return 'argon2'
 210            elif kdf_parameters['$UUID'].value == kdf_uuids['argon2id']:
 211                return 'argon2id'
 212            elif kdf_parameters['$UUID'].value == kdf_uuids['aeskdf']:
 213                return 'aeskdf'
 214
 215    @property
 216    def transformed_key(self):
 217        """`bytes`: transformed key used in database decryption.  May be cached
 218        and passed to `open` for faster database opening"""
 219        return self.kdbx.body.transformed_key
 220
 221    @property
 222    def database_salt(self):
 223       """`bytes`: salt of database kdf. This can be used for adding additional
 224       credentials which are used in extension to current keyfile."""
 225
 226       if self.version == (3, 1):
 227            return self.kdbx.header.value.dynamic_header.transform_seed.data
 228
 229       kdf_parameters = self.kdbx.header.value.dynamic_header.kdf_parameters.data.dict
 230       return kdf_parameters['S'].value
 231
 232    @property
 233    def payload(self):
 234        """`construct.Container`: Encrypted payload of keepass database"""
 235
 236        # check if payload is decrypted
 237        if self.kdbx.body.payload is None:
 238            raise ValueError("Database is not decrypted")
 239        else:
 240            return self.kdbx.body.payload
 241
 242    @property
 243    def tree(self):
 244        """`lxml.etree._ElementTree`: database XML payload"""
 245        return self.payload.xml
 246
 247    @property
 248    def root_group(self):
 249        """`Group`: root Group of database"""
 250        return self.find_groups(path='', first=True)
 251
 252    @property
 253    def recyclebin_group(self):
 254        """`Group`: RecycleBin Group of database"""
 255        elem = self._xpath('/KeePassFile/Meta/RecycleBinUUID', first=True)
 256        recyclebin_uuid = uuid.UUID( bytes = base64.b64decode(elem.text) )
 257        return self.find_groups(uuid=recyclebin_uuid, first=True)
 258
 259    @property
 260    def groups(self):
 261        """`list` of `Group`: all groups in database
 262        """
 263        return self.find_groups()
 264
 265    @property
 266    def entries(self):
 267        """`list` of `Entry`: all entries in database,
 268        excluding history"""
 269        return self.find_entries()
 270
 271    @property
 272    def database_name(self):
 273        """`str`: Name of database"""
 274        elem = self._xpath('/KeePassFile/Meta/DatabaseName', first=True)
 275        return elem.text
 276
 277    @database_name.setter
 278    def database_name(self, name):
 279        item = self._xpath('/KeePassFile/Meta/DatabaseName', first=True)
 280        item.text = str(name)
 281
 282    @property
 283    def database_description(self):
 284        """`str`: Description of the database"""
 285        elem = self._xpath('/KeePassFile/Meta/DatabaseDescription', first=True)
 286        return elem.text
 287
 288    @database_description.setter
 289    def database_description(self, name):
 290        item = self._xpath('/KeePassFile/Meta/DatabaseDescription', first=True)
 291        item.text = str(name)
 292
 293    @property
 294    def default_username(self):
 295        """`str` or `None`: default user.  `None` if not set"""
 296        elem = self._xpath('/KeePassFile/Meta/DefaultUserName', first=True)
 297        return elem.text
 298
 299    @default_username.setter
 300    def default_username(self, name):
 301        item = self._xpath('/KeePassFile/Meta/DefaultUserName', first=True)
 302        item.text = str(name)
 303
 304    def xml(self):
 305        """Get XML part of database as string
 306
 307        Returns:
 308            `str`: XML content of database
 309        """
 310        return etree.tostring(
 311            self.tree,
 312            pretty_print=True,
 313            standalone=True,
 314            encoding='utf-8'
 315        )
 316
 317    def dump_xml(self, filename):
 318        """ Dump the contents of the database to file as XML
 319
 320        Args:
 321            filename (`str`): path to output file
 322        """
 323        with open(filename, 'wb') as f:
 324            f.write(self.xml())
 325
 326    def xpath(self, xpath_str, tree=None, first=False, cast=False, **kwargs):
 327        """Look up elements in the XML payload and return corresponding object.
 328
 329        Internal function which searches the payload lxml ElementTree for
 330        elements via XPath.  Matched entry, group, and attachment elements are
 331        automatically cast to their corresponding objects, otherwise an error
 332        is raised.
 333
 334        Args:
 335            xpath_str (`str`): XPath query for finding element(s)
 336            tree (`_ElementTree`, `Element`, optional): use this
 337                element as root node when searching
 338            first (`bool`): If True, function returns first result or None.  If
 339                False, function returns list of matches or empty list.
 340                    (default `False`).
 341            cast (`bool`): If True, matches are instead instantiated as
 342                pykeepass Group, Entry, or Attachment objects.  An exception
 343                is raised if a match cannot be cast.  (default `False`)
 344
 345        Returns:
 346            `list` of `Group`, `Entry`, `Attachment`, or `lxml.etree.Element`
 347        """
 348
 349        if tree is None:
 350            tree = self.tree
 351        logger.debug('xpath query: ' + xpath_str)
 352        elements = tree.xpath(
 353            xpath_str, namespaces={'re': 'http://exslt.org/regular-expressions'}
 354        )
 355
 356        res = []
 357        for e in elements:
 358            if cast:
 359                if e.tag == 'Entry':
 360                    res.append(Entry(element=e, kp=self))
 361                elif e.tag == 'Group':
 362                    res.append(Group(element=e, kp=self))
 363                elif e.tag == 'Binary' and e.getparent().tag == 'Entry':
 364                    res.append(Attachment(element=e, kp=self))
 365                else:
 366                    raise Exception('Could not cast element {}'.format(e))
 367            else:
 368                res.append(e)
 369
 370        # return first object in list or None
 371        if first:
 372            res = res[0] if res else None
 373
 374        return res
 375
 376    _xpath = xpath
 377
 378    def _find(self, prefix, keys_xp, path=None, tree=None, first=False,
 379              history=False, regex=False, flags=None, **kwargs):
 380        """Internal function for converting a search into an XPath string"""
 381
 382        xp = ''
 383
 384        if not history:
 385            prefix += '[not(ancestor::History)]'
 386
 387        if path is not None:
 388
 389            first = True
 390
 391            xp += '/KeePassFile/Root/Group'
 392            # split provided path into group and element
 393            group_path = path[:-1]
 394            element = path[-1] if len(path) > 0 else ''
 395            # build xpath from group_path and element
 396            for group in group_path:
 397                xp += path_xp[regex]['group'].format(group, flags=flags)
 398            if 'Entry' in prefix:
 399                xp += path_xp[regex]['entry'].format(element, flags=flags)
 400            elif element and 'Group' in prefix:
 401                xp += path_xp[regex]['group'].format(element, flags=flags)
 402
 403        else:
 404            if tree is not None:
 405                xp += '.'
 406
 407            xp += prefix
 408
 409            # handle searching custom string fields
 410            if 'string' in kwargs:
 411                for key, value in kwargs['string'].items():
 412                    xp += keys_xp[regex]['string'].format(key, value, flags=flags)
 413
 414                kwargs.pop('string')
 415
 416            # convert uuid to base64 form before building xpath
 417            if 'uuid' in kwargs:
 418                kwargs['uuid'] = base64.b64encode(kwargs['uuid'].bytes).decode('utf-8')
 419
 420            # convert tags to semicolon separated string before building xpath
 421            # FIXME: this isn't a reliable way to search tags.  e.g. searching ['tag1', 'tag2'] will match 'tag1tag2
 422            if 'tags' in kwargs:
 423                kwargs['tags'] = ' and '.join(f'contains(text(),"{t}")' for t in kwargs['tags'])
 424
 425            # build xpath to filter results with specified attributes
 426            for key, value in kwargs.items():
 427                if key not in keys_xp[regex]:
 428                    raise TypeError('Invalid keyword argument "{}"'.format(key))
 429                if value is not None:
 430                    xp += keys_xp[regex][key].format(value, flags=flags)
 431
 432        res = self._xpath(
 433            xp,
 434            tree=tree._element if tree else None,
 435            first=first,
 436            cast=True,
 437            **kwargs
 438        )
 439
 440        return res
 441
 442    def _can_be_moved_to_recyclebin(self, entry_or_group):
 443        if entry_or_group == self.root_group:
 444            return False
 445        recyclebin_group = self.recyclebin_group
 446        if recyclebin_group is None:
 447            return True
 448        uuid_str = base64.b64encode( entry_or_group.uuid.bytes).decode('utf-8')
 449        elem = self._xpath('./UUID[text()="{}"]/..'.format(uuid_str), tree=recyclebin_group._element, first=True, cast=False)
 450        return elem is None
 451
 452
 453    # ---------- Groups ----------
 454
 455    from .deprecated import (
 456        find_groups_by_name,
 457        find_groups_by_notes,
 458        find_groups_by_path,
 459        find_groups_by_uuid,
 460    )
 461
 462    def find_groups(self, recursive=True, path=None, group=None, **kwargs):
 463        """ Find groups in a database
 464
 465        [XSLT style]: https://www.xml.com/pub/a/2003/06/04/tr.html
 466        [flags]: https://www.w3.org/TR/xpath-functions/#flags
 467
 468        Args:
 469            name (`str`): name of group
 470            first (`bool`): return first result instead of list (default `False`)
 471            recursive (`bool`): do a recursive search of all groups/subgroups
 472            path (`list` of `str`): do group search starting from path
 473            group (`Group`): search underneath group
 474            uuid (`uuid.UUID`): group UUID
 475            regex (`bool`): whether `str` search arguments contain [XSLT style][XSLT style] regular expression
 476            flags (`str`): XPath [flags][flags]
 477
 478        The `path` list is a full path to a group (ex. `['foobar_group', 'sub_group']`).  This implies `first=True`.  All other arguments are ignored when this is given.  This is useful for handling user input.
 479
 480        The `group` argument determines what `Group` to search under, and the `recursive` boolean controls whether to search recursively.
 481
 482        The `first` (default `False`) boolean controls whether to return the first matched item, or a list of matched items.
 483
 484        - if `first=False`, the function returns a list of `Group` or `[]` if there are no matches
 485        - if `first=True`, the function returns the first `Group` match, or `None` if there are no matches
 486
 487        Returns:
 488            `list` of `Group` if `first=False`
 489            or (`Group` or `None`) if `first=True`
 490
 491        Examples:
 492        ``` python
 493        >>> kp.find_groups(name='foo', first=True)
 494        Group: "foo"
 495
 496        >>> kp.find_groups(name='foo.*', regex=True)
 497        [Group: "foo", Group "foobar"]
 498
 499        >>> kp.find_groups(path=['social'], regex=True)
 500        [Group: "social", Group: "social/foo_subgroup"]
 501
 502        >>> kp.find_groups(name='social', first=True).subgroups
 503        [Group: "social/foo_subgroup"]
 504        ```
 505        """
 506
 507        prefix = '//Group' if recursive else '/Group'
 508        res = self._find(prefix, group_xp, path=path, tree=group, **kwargs)
 509        return res
 510
 511    def add_group(self, destination_group, group_name, icon=None, notes=None):
 512        """Create a new group and all parent groups, if necessary
 513
 514        Args:
 515            destination_group (`Group`): parent group to add a new group to
 516            group_name (`str`): name of new group
 517            icon (`str`): icon name from `icons`
 518            notes (`str`): group notes
 519
 520        Returns:
 521            `Group`: newly added group
 522        """
 523        logger.debug('Creating group {}'.format(group_name))
 524
 525        if icon:
 526            group = Group(name=group_name, icon=icon, notes=notes, kp=self)
 527        else:
 528            group = Group(name=group_name, notes=notes, kp=self)
 529        destination_group.append(group)
 530
 531        return group
 532
 533    def delete_group(self, group):
 534        group.delete()
 535
 536    def move_group(self, group, destination_group):
 537        """Move a group"""
 538        destination_group.append(group)
 539
 540    def _create_or_get_recyclebin_group(self, **kwargs):
 541        existing_group = self.recyclebin_group
 542        if existing_group is not None:
 543            return existing_group
 544        kwargs.setdefault('group_name', 'Recycle Bin')
 545        group = self.add_group( self.root_group, **kwargs)
 546        elem = self._xpath('/KeePassFile/Meta/RecycleBinUUID', first=True)
 547        elem.text = base64.b64encode(group.uuid.bytes).decode('utf-8')
 548        return group
 549
 550    def trash_group(self, group):
 551        """Move a group to the RecycleBin
 552
 553        The recycle bin is created if it does not exit. ``group`` must be an empty Group.
 554
 555        Args:
 556            group (`Group`): Group to send to the RecycleBin
 557        """
 558        if not self._can_be_moved_to_recyclebin(group):
 559            raise UnableToSendToRecycleBin
 560        recyclebin_group = self._create_or_get_recyclebin_group()
 561        self.move_group( group, recyclebin_group)
 562
 563    def empty_group(self, group):
 564        """Delete all entries and subgroups of a group.
 565
 566        This does not delete the group itself
 567
 568        Args:
 569            group (`Group`): Group to empty
 570        """
 571        while len(group.subgroups):
 572            self.delete_group(group.subgroups[0])
 573        while len(group.entries):
 574            self.delete_entry(group.entries[0])
 575
 576    # ---------- Entries ----------
 577
 578
 579    from .deprecated import (
 580        find_entries_by_notes,
 581        find_entries_by_password,
 582        find_entries_by_path,
 583        find_entries_by_string,
 584        find_entries_by_title,
 585        find_entries_by_url,
 586        find_entries_by_username,
 587        find_entries_by_uuid,
 588    )
 589
 590    def find_entries(self, recursive=True, path=None, group=None, **kwargs):
 591        """Returns entries which match all provided parameters
 592        Args:
 593            path (`list` of (`str` or `None`), optional): full path to an entry
 594                (eg. `['foobar_group', 'foobar_entry']`).  This implies `first=True`.
 595                All other arguments are ignored when this is given.  This is useful for
 596                handling user input.
 597            title (`str`, optional): title of entry to find
 598            username (`str`, optional): username of entry to find
 599            password (`str`, optional): password of entry to find
 600            url (`str`, optional): url of entry to find
 601            notes (`str`, optional): notes of entry to find
 602            otp (`str`, optional): otp string of entry to find
 603            string (`dict`): custom string fields.
 604                (eg. `{'custom_field1': 'custom value', 'custom_field2': 'custom value'}`)
 605            uuid (`uuid.UUID`): entry UUID
 606            tags (`list` of `str`): entry tags
 607            autotype_enabled (`bool`, optional): autotype string is enabled
 608            autotype_sequence (`str`, optional): autotype string
 609            autotype_window (`str`, optional): autotype target window filter string
 610            group (`Group` or `None`, optional): search under this group
 611            first (`bool`, optional): return first match or `None` if no matches.
 612                Otherwise return list of `Entry` matches. (default `False`)
 613            history (`bool`): include history entries in results. (default `False`)
 614            recursive (`bool`): search recursively
 615            regex (`bool`): interpret search strings given above as
 616                [XSLT style](https://www.xml.com/pub/a/2003/06/04/tr.html) regexes
 617            flags (`str`): regex [search flags](https://www.w3.org/TR/xpath-functions/#flags)
 618
 619        Returns:
 620            `list` of `Entry` if `first=False`
 621            or (`Entry` or `None`) if `first=True`
 622
 623        Examples:
 624
 625        ``` python
 626        >>> kp.find_entries(title='gmail', first=True)
 627        Entry: "social/gmail (myusername)"
 628
 629        >>> kp.find_entries(title='foo.*', regex=True)
 630        [Entry: "foo_entry (myusername)", Entry: "foobar_entry (myusername)"]
 631
 632        >>> entry = kp.find_entries(title='foo.*', url='.*facebook.*', regex=True, first=True)
 633        >>> entry.url
 634        'facebook.com'
 635        >>> entry.title
 636        'foo_entry'
 637        >>> entry.title = 'hello'
 638
 639        >>> group = kp.find_group(name='social', first=True)
 640        >>> kp.find_entries(title='facebook', group=group, recursive=False, first=True)
 641        Entry: "social/facebook (myusername)"
 642        ```
 643        """
 644
 645        prefix = '//Entry' if recursive else '/Entry'
 646        res = self._find(prefix, entry_xp, path=path, tree=group, **kwargs)
 647
 648        return res
 649
 650
 651    def add_entry(self, destination_group, title, username,
 652                  password, url=None, notes=None, expiry_time=None,
 653                  tags=None, otp=None, icon=None, force_creation=False):
 654
 655        """Create a new entry
 656
 657        Args:
 658            destination_group (`Group`): parent group to add a new entry to
 659            title (`str`, or `None`): title of new entry
 660            username (`str` or `None`): username of new entry
 661            password (`str` or `None`): password of new entry
 662            url (`str` or `None`): URL of new entry
 663            notes (`str` or `None`): notes of new entry
 664            expiry_time (`datetime.datetime`): time of entry expiration
 665            tags (`list` of `str` or `None`): entry tags
 666            otp (`str` or `None`): OTP code of object
 667            icon (`str`, optional): icon name from `icons`
 668            force_creation (`bool`): create entry even if one with identical
 669                title exists in this group (default `False`)
 670
 671        If ``expiry_time`` is a naive datetime object
 672        (i.e. ``expiry_time.tzinfo`` is not set), the timezone is retrieved from
 673        ``dateutil.tz.gettz()``.
 674
 675
 676        Returns:
 677            `Group`: newly added group
 678        """
 679
 680        entries = self.find_entries(
 681            title=title,
 682            username=username,
 683            first=True,
 684            group=destination_group,
 685            recursive=False
 686        )
 687
 688        if entries and not force_creation:
 689            raise Exception(
 690                'An entry "{}" already exists in "{}"'.format(
 691                    title, destination_group
 692                )
 693            )
 694        else:
 695            logger.debug('Creating a new entry')
 696            entry = Entry(
 697                title=title,
 698                username=username,
 699                password=password,
 700                notes=notes,
 701                otp=otp,
 702                url=url,
 703                tags=tags,
 704                expires=True if expiry_time else False,
 705                expiry_time=expiry_time,
 706                icon=icon,
 707                kp=self
 708            )
 709            destination_group.append(entry)
 710
 711        return entry
 712
 713    def delete_entry(self, entry):
 714        """Delete entry
 715
 716        Args:
 717            entry (`Entry`): entry to delete
 718        """
 719        entry.delete()
 720
 721    def move_entry(self, entry, destination_group):
 722        """Move entry to group
 723
 724        Args:
 725            entry (`Entry`): entry to move
 726            destination_group (`Group`): group to move to
 727        """
 728        destination_group.append(entry)
 729
 730    def trash_entry(self, entry):
 731        """Move an entry to the RecycleBin
 732
 733        The recycle bin is created if it does not exit.
 734
 735        Args:
 736            entry (`Entry`): Entry to send to the RecycleBin
 737        """
 738        if not self._can_be_moved_to_recyclebin(entry):
 739            raise UnableToSendToRecycleBin
 740        recyclebin_group = self._create_or_get_recyclebin_group()
 741        self.move_entry( entry, recyclebin_group)
 742
 743    # ---------- Attachments ----------
 744
 745    def find_attachments(self, recursive=True, path=None, element=None, **kwargs):
 746        """ Find attachments in database
 747
 748        Args:
 749            id (`int` or `None`): attachment ID to match
 750            filename (`str` or `None`): filename to match
 751            element (`Entry` or `Group` or `None`): entry or group to search under
 752            recursive (`bool`): search recursively (default `True`)
 753            regex (`bool`): whether `str` search arguments contain [XSLT style][XSLT style] regular expression
 754            flags (`str`): XPath [flags][flags]
 755            history (`bool`): search under history entries. (default `False`)
 756            first (`bool`): If True, function returns first result or None.  If
 757                False, function returns list of matches or empty list.  (default
 758                `False`).
 759        """
 760
 761        prefix = '//Binary' if recursive else '/Binary'
 762        res = self._find(prefix, attachment_xp, path=path, tree=element, **kwargs)
 763
 764        return res
 765
 766    @property
 767    def attachments(self):
 768        """`list` of `Attachment`: all attachments in database"""
 769        return self.find_attachments(filename='.*', regex=True)
 770
 771    @property
 772    def binaries(self):
 773        """`list` of `bytes`: all attachment binaries in database.  The position
 774        within this list indicates the binary's ID"""
 775        if self.version >= (4, 0):
 776            # first byte is a prepended flag
 777            binaries = [a.data[1:] for a in self.payload.inner_header.binary]
 778        else:
 779            binaries = []
 780            for elem in self._xpath('/KeePassFile/Meta/Binaries/Binary'):
 781                if elem.text is not None:
 782                    if elem.get('Compressed') == 'True':
 783                        data = zlib.decompress(
 784                            base64.b64decode(elem.text),
 785                            zlib.MAX_WBITS | 32
 786                        )
 787                    else:
 788                        data = base64.b64decode(elem.text)
 789                else:
 790                    data = b''
 791                binaries.insert(int(elem.attrib['ID']), data)
 792
 793        return binaries
 794
 795    def add_binary(self, data, compressed=True, protected=True):
 796        """Add binary data to database.  Note this does not create an attachment (see `Entry.add_attachment`)
 797
 798        Args:
 799            data (`bytes`): binary data
 800            compressed (`bool`): whether binary data should be compressed.
 801                (default `True`).  Applies only to KDBX3
 802            protected (`bool`): whether protected flag should be set.  (default `True`).  Note
 803                Applies only to KDBX4
 804
 805        Returns:
 806            id (`int`): ID of binary in database
 807        """
 808        if self.version >= (4, 0):
 809            # add protected flag byte
 810            data = b'\x01' + data if protected else b'\x00' + data
 811            # add binary element to inner header
 812            c = Container(type='binary', data=data)
 813            self.payload.inner_header.binary.append(c)
 814        else:
 815            binaries = self._xpath(
 816                '/KeePassFile/Meta/Binaries',
 817                first=True
 818            )
 819            if compressed:
 820                # gzip compression
 821                compressor = zlib.compressobj(
 822                    zlib.Z_DEFAULT_COMPRESSION,
 823                    zlib.DEFLATED,
 824                    zlib.MAX_WBITS | 16
 825                )
 826                data = compressor.compress(data)
 827                data += compressor.flush()
 828            data = base64.b64encode(data).decode()
 829
 830            # set ID for Binary Element
 831            binary_id = len(self.binaries)
 832
 833            # add binary element to XML
 834            binaries.append(
 835                E.Binary(data, ID=str(binary_id), Compressed=str(compressed))
 836            )
 837
 838        # return binary id
 839        return len(self.binaries) - 1
 840
 841    def delete_binary(self, id):
 842        """Remove a binary from database and deletes attachments that reference it
 843
 844        Since attachments reference binaries by their positional index,
 845        attachments that reference binaries with ID > `id` will automatically be decremented
 846
 847        Args:
 848            id (`int`): ID of binary to remove
 849
 850        Raises:
 851            `IndexError`: raised when binary with given ID does not exist
 852        """
 853        try:
 854            if self.version >= (4, 0):
 855                # remove binary element from inner header
 856                self.payload.inner_header.binary.pop(id)
 857            else:
 858                # remove binary element from XML
 859                binaries = self._xpath('/KeePassFile/Meta/Binaries', first=True)
 860                binaries.remove(binaries.getchildren()[id])
 861        except IndexError:
 862            raise BinaryError('No such binary with id {}'.format(id))
 863
 864        # remove all entry references to this attachment
 865        for reference in self.find_attachments(id=id):
 866            reference.delete()
 867
 868        # decrement references greater than this id
 869        binaries_gt = self._xpath(
 870            '//Binary/Value[@Ref > "{}"]/..'.format(id),
 871            cast=True
 872        )
 873        for reference in binaries_gt:
 874            reference.id = reference.id - 1
 875
 876    # ---------- Misc ----------
 877
 878    def deref(self, value):
 879
 880        """Dereference [field reference][fieldref] of Entry
 881
 882        Args:
 883            ref (`str`): KeePass reference string to another field
 884
 885        Returns:
 886            `str`, `uuid.UUID` or `None` if no match found
 887
 888        [fieldref]: https://keepass.info/help/base/fieldrefs.html
 889        """
 890        if not value:
 891            return value
 892        references = set(re.findall(r'({REF:([TUPANI])@([TUPANI]):([^}]+)})', value))
 893        if not references:
 894            return value
 895        field_to_attribute = {
 896            'T': 'title',
 897            'U': 'username',
 898            'P': 'password',
 899            'A': 'url',
 900            'N': 'notes',
 901            'I': 'uuid',
 902        }
 903        for ref, wanted_field, search_in, search_value in references:
 904            wanted_field = field_to_attribute[wanted_field]
 905            search_in = field_to_attribute[search_in]
 906            if search_in == 'uuid':
 907                search_value = uuid.UUID(search_value)
 908            ref_entry = self.find_entries(first=True, **{search_in: search_value})
 909            if ref_entry is None:
 910                return None
 911            value = value.replace(ref, getattr(ref_entry, wanted_field))
 912        return self.deref(value)
 913
 914
 915    # ---------- Credential Changing and Expiry ----------
 916
 917    @property
 918    def password(self):
 919        """`str`: Get or set database password"""
 920        return self._password
 921
 922    @password.setter
 923    def password(self, password):
 924        self._password = password
 925        self.credchange_date = datetime.now(timezone.utc)
 926
 927    @property
 928    def keyfile(self):
 929        """`str` or `pathlib.Path` or `None`: get or set database keyfile"""
 930        return self._keyfile
 931
 932    @keyfile.setter
 933    def keyfile(self, keyfile):
 934        self._keyfile = keyfile
 935        self.credchange_date = datetime.now(timezone.utc)
 936
 937    @property
 938    def credchange_required_days(self):
 939        """`int`: Days until password update should be required"""
 940        e = self._xpath('/KeePassFile/Meta/MasterKeyChangeForce', first=True)
 941        if e is not None:
 942            return int(e.text)
 943
 944    @property
 945    def credchange_recommended_days(self):
 946        """`int`: Days until password update should be recommended"""
 947        e = self._xpath('/KeePassFile/Meta/MasterKeyChangeRec', first=True)
 948        if e is not None:
 949            return int(e.text)
 950
 951    @credchange_required_days.setter
 952    def credchange_required_days(self, days):
 953        path = '/KeePassFile/Meta/MasterKeyChangeForce'
 954        item = self._xpath(path, first=True)
 955        item.text = str(days)
 956
 957    @credchange_recommended_days.setter
 958    def credchange_recommended_days(self, days):
 959        path = '/KeePassFile/Meta/MasterKeyChangeRec'
 960        item = self._xpath(path, first=True)
 961        item.text = str(days)
 962
 963    @property
 964    def credchange_date(self):
 965        """`datetime.datetime`: get or set UTC time of last credential change"""
 966        e = self._xpath('/KeePassFile/Meta/MasterKeyChanged', first=True)
 967        if e is not None:
 968            return self._decode_time(e.text)
 969
 970    @credchange_date.setter
 971    def credchange_date(self, date):
 972        mk_time = self._xpath('/KeePassFile/Meta/MasterKeyChanged', first=True)
 973        mk_time.text = self._encode_time(date)
 974
 975    @property
 976    def credchange_required(self):
 977        """`bool`: Check if credential change is required"""
 978        change_date = self.credchange_date
 979        if change_date is None or self.credchange_required_days == -1:
 980            return False
 981        now_date = datetime.now(timezone.utc)
 982        return (now_date - change_date).days > self.credchange_required_days
 983
 984    @property
 985    def credchange_recommended(self):
 986        """`bool`: Check if credential change is recommended"""
 987        change_date = self.credchange_date
 988        if change_date is None or self.credchange_recommended_days == -1:
 989            return False
 990        now_date = datetime.now(timezone.utc)
 991        return (now_date - change_date).days > self.credchange_recommended_days
 992
 993    # ---------- Datetime Functions ----------
 994
 995    def _encode_time(self, value):
 996        """`bytes` or `str`: Convert datetime to base64 or plaintext string"""
 997
 998        if self.version >= (4, 0):
 999            diff_seconds = int(
1000                (
1001                    value -
1002                    datetime(
1003                        year=1,
1004                        month=1,
1005                        day=1,
1006                        tzinfo=timezone.utc
1007                    )
1008                ).total_seconds()
1009            )
1010            return base64.b64encode(
1011                struct.pack('<Q', diff_seconds)
1012            ).decode('utf-8')
1013        else:
1014            return value.isoformat()
1015
1016    def _decode_time(self, text):
1017        """`datetime.datetime`: Convert base64 time or plaintext time to datetime"""
1018
1019        if self.version >= (4, 0):
1020            # decode KDBX4 date from b64 format
1021            try:
1022                return (
1023                    datetime(year=1, month=1, day=1, tzinfo=timezone.utc) +
1024                    timedelta(
1025                        seconds=struct.unpack('<Q', base64.b64decode(text))[0]
1026                    )
1027                )
1028            except BinasciiError:
1029                return datetime.fromisoformat(text.replace('Z','+00:00')).replace(tzinfo=timezone.utc)
1030        else:
1031            return datetime.fromisoformat(text.replace('Z','+00:00')).replace(tzinfo=timezone.utc)