Note: if you like this project, don't forget to vote for it!
Index
Introduction
Nowadays you need to remember many passwords. You need a password for the Windows network logon, your e-mail account, your website's FTP password, online passwords (like CodeProject member account), and so on. The list is endless. Also, you should use a different password for each account, because if you use only one password everywhere and someone gets this password, you have a problem... A serious problem. He would have access to your e-mail account, website, etc. Unimaginable.
But who can remember all those passwords? Nobody, but KeePass can. KeePass is a free, open source, light-weight and easy-to-use password manager. With this tool, you only need to remember one single, strong master password and/or carry a key file with you (more about this below).
The program stores your passwords in a highly encrypted database. This database consists of only one file, so it can be transferred from one computer to another easily, and backups are easy to create.
KeePass supports groups, into which you can sort your entries. Examples for groups are "Windows", "Network", "Internet" and "Homebanking", but you can freely add and delete groups.
KeePass 1.x is a Windows application. It has been developed using Microsoft Visual C++ with MFC classes. The .NET Framework is not required, nor are any other special DLLs. So it should run on all Windows operating systems without installation of any additional library.
KeePass is distributed under the terms of the GNU General Public License v2. See the file License.txt in the downloadable ZIP package for details.
Master Passwords and Key Files
KeePass stores your passwords securely in an encrypted database. This database is encrypted using a master password and/or a key file.
If you use a master password, you only have to remember this one password (which should be long and complex to provide good security).
KeePass can also get (a part of) the master key from a key file (not to be confused with the database file). A key file may be any file, but it's recommended to use a file that contains at least 256 bits of entropy. KeePass can generate such a file for you. The key file should be stored separately, e.g. on a USB stick. If it is stored together with the database file, it doesn't provide any protection (as an attacker would get both files).
For best security, you can combine the two methods: you can use a master password and a key file together, i.e. both are then needed to decrypt the database file. This provides two-factor security: the master password is something that you know and the key file is something that you have.
If you forget the master password or lose the key file, the database cannot be decrypted and all data stored in it is lost. The database is encrypted using very secure algorithms (AES and Twofish) and there is no backdoor and no universal key that can open your database.
First Steps
I will now guide you through the first steps of using KeePass. If you are experienced and don't need this, just skip this section.
Download the binary ZIP file and unpack it. KeePass doesn't need to be installed; just unpack the ZIP file and it's ready.
So, let's start the KeePass.exe file. You'll see two gray lists, a preview area, a menu bar and a status bar.
KeePass by default speaks English. If you want a different language, go to the KeePass website and download one of the translations offered there (over 40 languages are available). Unpack the translation package into the Languages folder in the KeePass application directory, start KeePass, go "View" → "Change Language..." and select your language.
Let's create a new database: go "File" → "New". You'll see a dialog where you can enter the master password for this database (see the section above for a screenshot of this dialog). If you want to use a key file, specify its location (if you choose an existing file, KeePass asks you whether you want to reuse or overwrite it).
After you've created the new database, you see an almost empty screen. In the left tree view, you see a few standard groups which have been automatically created for you: "General", "Windows", "Network", "Internet", "eMail" and "Homebanking". If you wish, you can delete these default groups and freely create your own ones. In the following screenshot, I've created a few sample groups and entries:
The list view on the right is currently empty in your case (you won't see sample entries as in the screenshot above). That's the entry list. Each password will get its own entry. Various fields are supported, like title, user name, URL, password, notes, expiry time, file attachment, icon and some more.
As you can see in the screenshot, you can add, edit/view, move and delete entries. You can search entries in the whole database or only in the currently selected group. The context menu also allows you to copy the user name or password to the clipboard (which will be cleared automatically in a few seconds when you do this) or visit the URL of the entry.
Your first step will be to add an entry. Right-click in the entry list on the right and select "Add Entry". The following dialog will open:
Pretty self-explanatory I think. When you click on the "●●●" button, the passwords will be shown as plain text, i.e. not hidden by '●' symbols.
When you decide to use KeePass, I recommend to let KeePass generate passwords for you using the built-in password generator. The generated passwords are less biased than when a human "generates" them. The password generation dialog is also pretty self-explanatory and you shouldn't have any problems understanding what the various options do.
Features
You should by now be able to use the basic features of KeePass. I will now present some more features of KeePass.
Transferring Passwords
There are various ways to get the passwords stored in KeePass into other windows. The first, and most simple method is copying them to the clipboard. For this, just double-click onto the specific field in the main entry list. Example: if you want to copy the password of an entry, move the mouse cursor onto the password field of the entry in the main entry list and double-click; the password is then copied to the clipboard. KeePass has an option for clearing the clipboard automatically after some time; this prevents leaving sensitive data in the clipboard.
The second method is drag&drop. Like in the first method, move the mouse cursor onto the field that you want to use, press and hold the left mouse button and drag the data into the target window.
The third and most powerful method is auto-type. Auto-Type types user names, passwords and other data into other windows for you. The default auto-type sequence is {USERNAME}{TAB}{PASSWORD}{ENTER}, i.e. first the user name is typed, the Tab key is pressed, the password is typed, and Enter is pressed. However, this sequence is customizable per entry. This makes the auto-type feature applicable to all windows and web forms you'll ever see. There are two methods to invoke auto-type:
- Explicitly. Select the entry that you want to auto-type, right-click onto it and click "Perform Auto-Type". KeePass will bring the previous window to the foreground and auto-type into this window.
- Global hot key. This is the most powerful method. You leave KeePass running in the background. When you're on a site that requires a login, just press a hot key (Ctrl+Alt+A by default). Based on the title of the target window, KeePass locates the correct entry and auto-types it into the target window.
Exporting, Importing, Printing, Plugins
KeePass can export the database to TXT, HTML, XML and CSV files. It can import various formats (like CSV, CodeWallet TXT, PwSafe v2 TXT and Personal Vault TXT).
Of course, you can also print the database contents. Before printing, you can define which fields (title, user name, etc.) you want to see.
KeePass features a plugin architecture. You can get many plugins from the KeePass website. These plugins provide additional import/export capabilities from/to other file formats, integration features, automatic database backup functionalities and much more.
Open Source and Other Platforms
And the best: it's completely free and you have full access to its source code! There are various ports of KeePass to other platforms; visit the KeePass website for a list of ports.
Security
All databases are encrypted using the Advanced Encryption Standard (AES/Rijndael, a 128-bit block cipher using a 256-bit key) or the Twofish algorithm (another 128-bit block cipher using a 256-bit key). I've chosen the CBC block cipher mode. A 128-bit initialization vector (IV) is generated randomly each time you save the database.
In order to generate the 256-bit key for AES/Twofish, the master key components (master password and/or contents of a key file) together with a random salt (which is generated randomly each time you save the database and is saved in it; this prevents a precomputation of keys) are hashed using the cryptographically secure hash algorithm SHA-256 and the hash is then transformed using a key derivation function (see below).
We need to generate several cryptographically secure random bytes (for the encryption IV, the master key salt, etc.). For this, KeePass first collects entropy from several sources: current tick count, performance counter, system date/time, mouse cursor position, memory status (free virtual memory, etc.), active window, clipboard owner, various process and thread IDs, various window focus handles (active window, desktop, ...), window message stack, process heap status, process startup information and several system information structures. This entropy is collected in a pool. To generate random bytes, the pool is hashed together with a counter using SHA-256 to form the random bytes. The counter is increased then; this way we can produce as many secure random bytes as we need.
Each time you start KeePass, it performs a quick self-test, where the cryptographic algorithms are tested against their correct test vectors.
Protection Against Dictionary and Guessing Attacks
KeePass offers some protection against guessing and dictionary attacks. You can't completely prevent dictionary and guessing attacks; nothing prevents an attacker to just try possible keys and look whether the database decrypts. However, what we can do (and KeePass does) is to make it harder: transforming the key in N rounds using an AES-based key derivation function adds a constant time factor for each key, such that an attacker needs a lot more time.
By default, KeePass uses N = 60000. With this number, it's possible to open a database on systems with slow processors (mobile phones, etc.) in an acceptable time; PCs usually can do a lot more rounds. If you are using KeePass on fast devices only, you can increase the number of rounds (you can set it in the database settings dialog).
Process Memory Protection
While KeePass is running, sensitive data in the process memory is encrypted using the CryptProtectMemory function of the Windows Data Protection API (DPAPI). For details (how the feature works exactly, its limitations, etc.), see Process Memory Protection.
Locking the Workspace
What happens when you lock the KeePass workspace? Why are you sometimes prompted to save the database first? It's simple: locking the KeePass workspace closes the database completely, but remembers the last view settings (i.e. which group and entry you selected, list position, etc.). This provides maximum security (unlocking the workspace is as hard as opening the database the normal way) and prevents data loss (a computer crash is no problem while the workspace is locked).
Internals
There is a password manager class called CPwManager that handles all the operations concerning the database. It provides methods for editing groups and entries, move them, etc. This core class is portable; it doesn't depend on any Windows system-specific functions.
The class CPwExport handles all export functions. It can export the complete database or just one group.
The CNewRandom class implements the cryptographically secure pseudo-random number generator that's described above.
The files MemUtil.* contain some memory-related functions like one for securely erasing a buffer. In StrUtil.*, string-related functions can be found (like one for erasing CString objects). Miscellaneous functions related to the application, process and file system are in AppUtil.* (like a function for securely deleting files).
Frequently Asked Questions (FAQ)
Here's a mini version of the FAQ. You can find the complete FAQ here: Technical FAQ.
How can I help you?
Donate, make a translation, test new releases and submit bugs, and spread the word about KeePass.
E-Mail field?
In short: I won't implement it, because it would reduce usability. You can find the full answer here: Technical FAQ.
What are those 'Secure Edit Controls'?
Secure Edit Controls are special password edit controls that are resistant to window spies and memory dumpers. More about this here: Secure Edit Controls.
What are the differences between KeePass 1.x and 2.x?
See the Edition Comparison and the Development Status FAQ.
Thanks and Acknowledgements
At this place I want to thank some people for their support, ideas and source code contributions (in no particular order):
- Szymon Stefanek - for his C++ implementation of the Rijndael cipher.
- Brian Gladman - for his C implementation of the SHA-2 (256/384/512) hashing algorithms.
- Alvaro Mendez - MFC class for validating edit controls (
CAMSEdit). - Brent Corkum - for his XP-like menu (
BCMenu). - Davide Calabro - for his
CButtonST class. - Zorglab, Chris Maunder, Alexander Bischofberger, James White, Descartes Systems Sciences Inc. - MFC class for color pickers (
CColourPickerXP). - Peter Mares - for his side banner window class (
CKCSideBannerWnd). - Chris Maunder - for his
CSystemTray class. - Hans Dietrich, Chris Maunder - for the
XHyperLink class. - Lallous - for the
CSendKeys engine. - PJ Naughter - for the single instance checking class.
- Bill Rubin - Command line C++ classes.
- Boost Developers - Boost C++ libraries.
- All translators.
- Paul Tannard, Wellread1, Michael Scheer - for feature suggestions, bug reports and helping others in the forums.
- Daniel Turini - for suggesting "KeePass" as the name of the project.
- Christopher Bolin, Victor Andreyenkov - for the nice KeePass main program icons.
- David Vignoni - for the nice icon theme 'Nuvola' (which is freely usable under the LGPL license).
History
You can find the latest news and the version history on the KeePass website.
Some Final Words
I will upload the most important and major versions of KeePass 1.x here on CodeProject. For KeePass 2.x and the latest unstable releases, visit the KeePass website.
That's it. I hope I was able to make your life a bit easier with this tool :-)
