1What is this project?
2=====================
3
4This project is a from-scratch C implementation of reading and writing KeePass
51.x format password databases.  From this simple base, other programs can be
6written to manipulate KeePass databases without researching all of the innards
7of the KeePass database structure.
8
9What good is that?
10==================
11
12Well, if you wanted to write a client with a different interface, such as
13command-line or a GUI on a limited device, you'd have significant trouble when
14looking at the KeePass and KeePassX projects.  Extricating the database
15handling code from the interface code is difficult if not impossible.  It just
16made more sense to start fresh and make a simple C library that could be used
17for other programs and to make bindings to other languages.
18
19How do I use it?
20================
21
22The header file should give a good idea as to the main functions.  The library
23is incredibly simple because it's focused on the encryption and decryption.
24How the client wants to modify the database is entirely up to that program.  As
25long as the database structure is consistent, the library will encrypt it.
26
27Why don't you use mlock?
28========================
29
30I've seen it suggested before.  I even deeply considered it when I started out
31writing this library.  The idea being that a program should mlock all of the
32memory that stores passwords so it won't be written to a swap device.  It's a
33great idea until you realize a significant problem.  The passwords might not
34touch swap while in your program, but once it enters the paste buffer or gets
35written to the screen who knows where it will get dropped.  Sure, you can say,
36"It wasn't my program!" but that doesn't help anyone.
37
38Once you realize that passwords will probably leak to the swap through other
39sources (along with all sorts of other information), it becomes obvious that
40encrypting the swap is the real solution.  And after you've encrypted your
41swap, there's no reason to use mlock.
42
43Supporting 2.x databases
44========================
45
46I haven't looked into 2.x very much, but the feature list mentions that its
47internal structure is XML.  The bulk of this library is for parsing/generating
48the binary format of KeePass 1.x databases.  This suggests that it would be
49much better off as a new, separate project, but I would not expect a
50"libkpass2" soon.
51
52Should I open databases I don't trust
53=====================================
54
55The library should resist overflows and the like from malformed databases.
56However, as the original specification never specified if all fields must be
57present for the groups/entries in the database.  Indeed, it is easy to write a
58database that omits portions of each group or entry and still comply to the
59format.  With this in mind, the programs that use the library must keep in mind
60that some fields may be null, despite whether it makes sense or not.  Enforcing
61the existence of every entity may appear later as some sort of "strict mode".
62
63There are still ways to make a database that parses but is nonsense.  For
64example, having duplicate UUIDs on different entries would potentially drive a
65client to do some odd things if it wasn't aware of it.  Groups with parent
66groups that don't exist.  There isn't anything in the database to enforce
67consistency, which is probably part of the drive to move to XML for version
682.x.
69