https://github.com/libkeepass/libkeepass
Python module to read KeePass 1.x/KeePassX (v3) and KeePass 2.x (v4) files
https://github.com/libkeepass/libkeepass
keepass keepassx keepassxc library
Last synced: 5 months ago
JSON representation
Python module to read KeePass 1.x/KeePassX (v3) and KeePass 2.x (v4) files
- Host: GitHub
- URL: https://github.com/libkeepass/libkeepass
- Owner: libkeepass
- License: other
- Created: 2014-03-14T19:11:55.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2020-10-03T04:47:34.000Z (over 4 years ago)
- Last Synced: 2024-10-29T02:08:30.799Z (6 months ago)
- Topics: keepass, keepassx, keepassxc, library
- Language: Python
- Size: 539 KB
- Stars: 103
- Watchers: 12
- Forks: 31
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-keepass - libkeepass - `python` Low-level Python (2.7/3.x) module to read KeePass (API libraries / Other clients)
README
libkeepass
==========
**This library has been deprecated by** `pykeepass`_
Low-level Python (2.7/3.x) module to read KeePass 1.x/KeePassX (.kdb) and KeePass 2.x (.kdbx v3)
files.
See `pykeepass`_ or `kppy`_ for higher level database access and editing.
.. _`pykeepass`: https://github.com/libkeepass/pykeepass
.. _`kppy`: https://github.com/raymontag/kppy
Warning
-------
This code makes no attempt to secure its memory.
Dependencies
-------------
- `pycryptodome`_
- lxml
.. _`pycryptodome`: https://github.com/Legrandin/pycryptodome
KeePass 1.x support
-------------------
The v3 reader will parse the v3 binary format and put groups into the "groups"
attribute, and entries into the "entries" attribute. The special icon entry is
parsed and icons can be accessed via the "icons" attribute. Other special
entries are not parsed and seen as regular entries.
Only passwords are supported.
No write support.
KeePass 2.x support
-------------------
(Note: no support for KDBX v4 files)
The v4 reader can output the decrypted XML document that file format is based
on. It is also available as parsed objectified element tree.
The password elements in the XML document are protected in addition to the AES
encryption of the whole database. Switching between clear text and protected is
possible.
Passwords and key-file protection is supported.
Compressed and uncompressed files are supported.
There is basic "save as" write support. When writing the KeePass2 file, the
element tree is protected, serialized, compressed and encrypted according to the
settings in the file header and written to a stream.
ChaCha20 database encryption is supported. However its worth noting that
pycryptodome version 3.6.1 and earlier does not support 12-bytes nonces for
ChaCha20, which we require. Future versions of pycryptodome do support 12-byte
nonces. So if you're using 3.6.1 or earlier, decrypting a ChaCha20 encrypted
database will raise an exception. Decrypting AES and Twofish encrypted
databases will work as normal.
Currently the Argon2 key derivation algorithm and ChaCha20 protected passwords
are unsupported.
Merging/Synchronizing databases is also supported. Currently only the
synchronize and "overwrite if newer" modes are supported.
Merging
-------
Currently 3 merge modes are supported:
* **OVERWRITE_IF_NEWER** -- Entries are updated if there is a newer one in the
KDB being merged with and the previous entry is added to the entry history.
No Entry relocations nor deletions are done.
* **SYNCHRONIZE** -- This mode should be equivalent to the official keepass
*synchronize*, which does and `OVERWRITE_IF_NEWER`, Entry relocations, and
deletions.
* **SYNCHRONIZE_3WAY** -- This mode is similar to `SYNCHRONIZE`, except that
corresponding Entries are merged on a per field basis. This is desirable if
Entries in both the source and destination merge KDBs have diverged from
their common ancestor.
See `samples/merge.py`_ for an example of merging two KDBs in libkeepass. Keep
in mind that merging modifies the KDB being merged into. So make a copy if
you need the original.
.. _`samples/merge.py`: samples/merge.py
Examples
--------
.. code:: python
import libkeepass
filename = "input.kdbx"
with libkeepass.open(filename, password='secret', keyfile='keyfile.key') as kdb:
# print parsed element tree as xml
print(kdb.pretty_print())
# re-encrypt the password fields
kdb.protect()
print(kdb.pretty_print())
# or use kdb.obj_root to access the element tree
kdb.obj_root.findall('.//Entry')
# change the master password before writing
kdb.clear_credentials()
kdb.add_credentials(password="m04r_s3cr37")
# disable compression
kdb.set_compression(0)
# write to a new file
with open('output', 'wb') as output:
kdb.write_to(output)
# Alternatively, read a kdb4 file protected
with libkeepass.open(filename, password='secret', keyfile='keyfile.key', unprotect=False) as kdb:
# print parsed element tree as xml
print(kdb.pretty_print())
# decrypt the password fields
kdb.unprotect()
print(kdb.pretty_print())
Tools
-------
**kdbdiff** - Diff two keepass files
Currently the two file arguments can be KDB v3 or v4 databases or KDB v4
xml file. KDB v3 xml files can be supported natively once an importer is
written that creates a KDB3File from the v3 xml.
NOTE: This does a diff based on the entry name and path. So entries that
are moved will show up as added and deleted, even though the entries may be
identical other than their path.
Tools
-------
**shell** -- Basic command line shell to view a keepass database
**kdbutil** -- Utility to manipulate keepass databases with the following subcommands:
* **convert4** -- Convert a KDB v3 database to v4 format. This is better than
keepassx's (current) importer because it keeps entry uuids unique
across multiple conversions of the same KDB v3 database.
* **dump** -- Dump the inner xml of the keepass database.
WARNING: This will print passwords in clear-text.
* **shell** -- another simple shell for manipulating keepass database files.
Testing
-------
Make a virtualenv and install the requirements (or install through pip). Then run the tests script
.. code:: bash
pip install -e .
python -m tests
References
----------
Brett Viren's `code`_ was a starting point and some of his code is being
re-used unchanged
For v4 support reading the `original Keepass2 C#`_ source was used as inspiration
Keepass 2.x uses Salsa20 to protect data in XML. Currently `puresalsa20`_ is used and included.
For v3 read support, code was copied with some enhancements from WAKAYAMA
Shirou's `kptool`_.
.. _`original Keepass2 C#`: http://keepass.info
.. _`code`: https://github.com/brettviren/python-keepass
.. _`puresalsa20`: http://www.tiac.net/~sw/2010/02/PureSalsa20/index.html
.. _`kptool`: https://github.com/shirou/kptool)
Thanks to them and all others who came before are in order.
Contributors
------------
- fdemmer
- phpwutz
- nvamilichev
- crass
- pschmitt
- evidlo