Dominik Reichl's Homepage

Home - Freeware - Open-Source - Articles - Awards/Ratings - Contact - Send eMail - Set Bookmark

Dominik Reichl's
Homepage

Home

Software

Other

Information about me, how to
contact me and the imprint.

Open-Source applications, free C++
classes and other free sources.

Articles, papers, publications
and other texts.

Article

[Print version]

Note: If you like this project don't forget to vote for it!

Introduction

Today you need to remember many passwords. You need a password for the Windows network logon, your e-mail account, your homepage's FTP password, online passwords (like CodeProject member account), etc. etc. etc. The list is endless. Also, you should use different passwords 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, homepage, 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 safe for Windows. With this tool, you only need to remember one single, strong master password or carry a key-file with you (more about this soon).

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.

KeePass supports password groups, so you can sort your passwords (for example into "Windows", "Internet", "My Homepage", etc.).

KeePass is a Windows application. It has been developed using Microsoft Visual C++ with MFC classes. No .NET framework is required, nor 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 KeePass ZIP package for details.

Master passwords and key-disks

KeePass stores your passwords securely in an encrypted database. This database is locked with a master password and/or a key-disk:

If you use a master password you only have to remember one password or passphrase (which should be good then!).

If you lose this master password, all your other passwords in the database are lost, too. The database is encrypted using very secure algorithms (AES and Twofish) and there isn't any backdoor or a key which can open all databases. There is no way of recovering your passwords when you lose the key.

The database can alternatively be locked with a key-disk. A "key-disk" is just a normal disk which holds a file with the password bytes (KeePass can generate such disks for you).

If you lose the key-disk and have no backup copy of the key-file your passwords in the database are lost too, just as when you lose the master passphrase.

If you want to burn a master key CD-ROM select a writable drive (C: D: ?) and generate the master key-file. Burn the file "pwsafe.key" (i.e. C:\pwsafe.key or D:\pwsafe.key) into the root directory of your CD-ROM (E:\pwsafe.key). You can then insert the key CD-ROM and select the CD-ROM drive in KeePass to load the key from CD-ROM. For sure, you can do the steps above for any writable and readable media, not just CD-ROMs.

For even more security, you can combine the two methods. You can use a master password and a key-disk together, i.e. both are needed to unlock the database. This provides maximum, two-factor security: something that you know and something that you own is required.

The 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 (you don't need the source code package for now) and unzip somewhere where you find it again. KeePass doesn't need to be installed, just unpack the ZIP file and it runs.

So, let's start the KeePass.exe file. You see two gray lists, a menu bar and a status bar.

KeePass by default speaks English. If you want a different language, go to the KeePass homepage and download one of the translations offered there (currently there are over 26 languages). Unpack the translation file into the KeePass directory, start KeePass, go to the 'View' menu and change the language by clicking on 'Change Language...' and selecting your in the opening dialog.

Now let's create a new database. 'File' -> 'New Database'. You see a dialog where you must enter the master password for this database (see the section above for a screenshot of this dialog). If you want to use a key-disk instead, select a writable disk drive where the key-file will be stored.

You can also let KeePass generate a random master passphrase for you. But I doubt you can remember those... the generator is thought for creating passwords later for other passwords.

After you've created the new database, you see an almost empty screen. In the left tree view you see a few standard password groups which have been automatically created for you: General, Windows, Network, Internet, eMail and Homebanking. Note that you later can delete these standard 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 password entry list. Each password will get its own entry. Various fields are supported, like title, user name, URL, password, notes, expire time, file attachment, icon and some more.

As you can see in the screenshot you can add, modify/view, move and delete entries. You can search in the complete database or only in the current group view. 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 on the password list on the right and select "Add Entry". The following dialog will open:

Pretty self-explanatory I think. When you click on the three-blue-dots button, the entered passwords will be shown as plain-text, not as asterisks.

When you decide to use KeePass, I recommend you to let KeePass generate your passwords using the password generator. The generated passwords are just less biased as when a human mind "generates" them. The password generation dialog is also pretty self-explanatory and you shouldn't have any problems understanding what the various options do. When you click on the "Generate" button, a dialog will pop up asking you to generate some random numbers:

On the left side you can generate random input using the mouse. Click on the button "Use Mouse As Random Source" and move the mouse in the chaos field above until the progress bar below is full. KeePass will save the mouse position after a few pixels of movement. So free your mind and move the wildest figures with your mouse.

On the right side you can type something into the edit box. You can enter anything there. KeePass will use the text you enter here as a random source. You don't have to remember what you enter here. Enter many and different characters.

Features

You should by now be able to use the basic features of KeePass. I will now present some more of the features of KeePass.

Transferring the password:
There are various ways how you can get the passwords stored in KeePass into other windows. The first, most simple method is copying them to the clipboard. For this, just double-click onto the specific field in the main password list. Example: if you want to copy the password of entry X, point onto the password field of the entry in the main view and double-click. The password is copied to the clipboard. If you enabled the auto-clearing option, KeePass will clear the clipboard automatically after some seconds. This prevents you from forgetting to clear the clipboard yourself, leaving sensitive data in the clipboard.

The second method is drag-n-drop. As in method 1, point onto the field you want to use, click the left mouse button and hold it. Drag the data into other windows.

The third, most powerful method is auto-type. KeePass features a very mighty auto-type feature, which types user names, passwords, etc. into other windows for you. The default auto-typing sequence is: {USERNAME}{TAB}{PASSWORD}{TAB}{ENTER}. But this sequence is customizable, per entry (read the CHM documentation file that comes with KeePass for more about this). This makes the auto-type feature applicable to all windows and webforms you'll ever see. There are two submethods how to perform an auto-type:

Selecting an entry: Just select the entry that you want to get auto-typed, right-click onto it and click "Perform Auto-Type". KeePass will minimize itself, the window that had the focus before will come to the front. KeePass starts typing the data into this window.
Global hot key: This is the most powerful of all methods. You leave KeePass running in the background. As soon as you're on a site that requires a login (which you stored in KeePass before), just press a hot key (by default Ctrl-Alt-A). KeePass immediately auto-types the data into the target window.

Exporting and Importing, Plugins, Printing:
KeePass can export the database to TXT, HTML, XML or CSV files. It can import various formats, like CSV, CodeWallet TXT, PwSafe v2 TXT and Personal Vault TXT.

But KeePass also features a plugin architecture. You can get many free plugins from the KeePass homepage. These plugins provide additional import/export functions from/to many other formats, network functionalities, automatic database backup features and much more.

For sure, you can also print the complete password list or current list view. Shortly before printing, you can define which fields (title, user name, etc.) you want to get listed.

Open Source and other operating systems:
And the best: it's completely free and you have full access to its source code! There are already various ports of KeePass to other platforms in development. The 100% compatible PocketPC version is pretty stable already. A native Linux version (KDE/QT) has been started short time ago and a MacOSX is currently discussed on a mailing list. Visit the official KeePass homepage for more information about the latest status of these ports.

Security

In this section I will tell you how the databases are encrypted. If you aren't a cryptographer and don't know anything in the security field you won't understand that much and you maybe want to skip this section.

All databases are encrypted. Currently they are encrypted using the Advanced Encryption Standard (AES/Rijndael, 128-bit block cipher, using a 256-bit key) or the Twofish algorithm (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 secure hash algorithm SHA-256 (SHA-2 family) is used. The user key (the passphrase the user enters or the binary string in the key-file) plus a random salt is hashed using SHA-256. The random salt is generated randomly each time you save the database and saved in it. This prevents pre-computation of keys.

When using both master key and key-disk together, the final key is derived as follows: SHA-256(SHA-256(master password), key-file contents), i.e. the hash of the master password is concatenated with the key-file bytes and the resulting byte string is hashed with SHA-256 again. If the key-file contents aren't exactly 32 bytes (256 bits), they are hashed with SHA-256, too, to form a 256-bit key, i.e. the formula above changes to: SHA-256(SHA-256(master password), SHA-256(key-file contents)).

We need to generate several 'random' bytes (for the IV, the master key salt, etc.). For this, several pseudo-random sources are used: 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 pseudo-random data is collected in a random pool. To generate 16 random bytes, the pool is hashed (SHA-256) with a counter to form the final 16 random bytes. The counter is increased after 16 generated bytes, this way we can produce as many secure random bytes as we need.

Protection against dictionary and guessing attacks:
KeePass offers some protection against guessing and dictionary attacks (note: not brute-force attacks!). This is only needed when using master passwords, key-disks don't need this, they are more secure anyway. You can't really prevent dictionary and guessing attacks, nothing prevents an attacker to just try all possible keys and look if the database decrypts. But what we can do (and KeePass does) is to make it harder: by adding a constant time factor to the key initialization, we can make them as hard as we want. To generate the 'final' 256-bit key that is used for the block cipher, KeePass first hashes the users key (SHA-256), encrypts the result N times using the Advanced Encryption Standard (AES) and then hashes it again (SHA-256). Since the AES transformations aren't pre-computable, an attacker has to perform all the encryptions, too, otherwise he cannot try and see if the key he is currently trying is correct. The key used for the AES transformation is randomly generated and stored in the database header (this prevents pre-computing the AES transformations, although this is almost impossible anyway).

By default, KeePass sets N to 6000 encryption 'rounds' (full encryptions are meant, has nothing to do with the internal encryption rounds of AES). This has been done in order to provide compatibility to the PocketPC version (PocketPC processors are slower, therefore the key computation takes longer). Nothing prevents you from setting this to a much larger value (you can set it in the database options dialog), if you accept a one-second delay on your PC when opening a KeePass database, you can even set it to a few 100.000s. Think about this: an attacker now also needs much longer to try a key. If it takes him one second for one key, he can almost forget any dictionary and guessing attacks.

In-memory passwords protection:
While KeePass is running, your passwords are encrypted using a 'session key' (randomly generated at startup). This means, that even if you would dump the whole KeePass process memory to disk, you couldn't find the passwords (at least not in plain text). Note that this only applies to the passwords field, not to the usernames, etc. because of speed reasons. When you want to copy a password to the clipboard for example, KeePass first decrypts the password field using the session key, copies it to the clipboard and immediately re-encrypts it using the session key. Here, ARC4 is used as encryption algorithm, the session key has a fixed size of 12 bytes.

KeePass securely erases all security-critical memory when it's not needed any more, i.e. it overwrites those memory areas with random data before zeroing and releasing it (this applies to all security-critical memory, not only the passwords field).

Locking the workspace:
What happens when you lock the workspace? Why are you sometimes prompted to save the database first? It's simple: locking the workspace just 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 (what if your computer crashes while the workspace is locked?).

Each time you start KeePass, the program will perform a quick self-test where the AES/Rijndael cipher and the SHA-256 are tested against their correct test vectors.

Internals

There is a password manager class (CPwManager) which handles all the operations concerning the database. It exports functions for editing groups, edit password entries, move them, etc. This core class is portable, it doesn't depend on any Windows system-specific functions.

The class CPwExport handles all the export functions. It can export the complete database or just one group. I decided not to include an XML library which would blow up the KeePass application horribly. Only XML export is implemented for now, a XML importing plugin exists.

The file "memutils.h" contains some memory and buffer functions like securely erasing a buffer by overwriting it several times before setting it to zero, the same for CStrings, a routine for copying strings to the Windows clipboard and a routine for securely deleting files.

The CNewRandom class is a new pseudo-random number generator. It's based on the SHA-256 hash which hashes random sources with a counter to generate secure random bytes.

Frequently asked questions (FAQ)

Here's a mini-version of the KeePass FAQ. You can find the complete, full FAQ here: http://keepass.info/help/base/faq.html.

How can I help you?
Donate, make a translation, test new releases and submit bugs, spread the word that KeePass is good :)

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: full 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.
Dr Brian Gladman - for his C implementation of the SHA-2 (256/384/512) hashing algorithms.
Brent Corkum - for his XP-like menu (BCMenu).
Davide Calabro - for his CButtonST class.
Peter Mares - for his side banner window class.
Chris Maunder - for his CSystemTray class.
Hans Dietrich - for his XHyperLink class.
Daniel Turini - for suggesting "KeePass" as name of the project.
Christopher Bolin - for the nice KeePass main program icons.
Microsoft - for the nice XP icons used as client icons for the password entries.
Lallous - for the nice SendKeys engine.
PJ Naughter - for the single instance checking class.
DonAngel - for creating and maintaining the Bulgarian translation.
Petr Chramosta - for creating and maintaining the Czech translation.
Henrik Gregersen - for creating and maintaining the Danish translation.
Kees Koenders - for creating and maintaining the Dutch translation.
Andri Viiand - for creating and maintaining the Estonian translation.
Marc Tissot - for creating and maintaining the French translation.
Wasilis Mandratzis - for creating and maintaining the Greek translation.
Tomer Shalev - for creating and maintaining the Hebrew translation.
documan - for creating and maintaining the Hungarian translation.
Mauro Rossi - for creating and maintaining the Italian translation.
Hiroki Matsumoto - for creating and maintaining the Japanese translation.
Park Dae Beom - for creating and maintaining the Korean translation.
Donaldas Apanavicius - for creating and maintaining the Lithuian translation.
Oliver Noveski - for creating and maintaining the Macedonian translation.
Jo Chapparal - for creating and maintaining the Norwegian translation.
Maciej Chojnacki - for creating and maintaining the Polish translation.
Fabio Negri Cicotti - for creating and maintaining the Portuguese translation.
Varrey - for creating and maintaining the Russian translation.
Leo Dou - for creating and maintaining the Simplified Chinese translation.
Radoslav Bielik - for creating and maintaining the Slovak translation.
Marcel Trujillo - for creating and maintaining the Spanish translation.
Alexander Pettersson / (Michael Åström) - for creating and maintaining the Swedish translation.
Kao Shiang-Yuan - for creating and maintaining the traditional Chinese translation.
Erhan Burhan - for creating and maintaining the Turkish translation.
Alexey Zinchuk - for creating and maintaining the Ukrainian translation.
(note that this may not be the complete translations list, see the translations page for all translations)
Paul Tannard - for feature suggestions, bug reports and helping others in the forums.
Michael Scheer - for feature suggestions, bug reports and helping others in the forums.
David Vignoni - for the nice icon theme 'Nuvola' (which is freely usable under the LGPL license).
The UPX team - for the UPX executable compressor

History

You can find the latest news and version history on the KeePass homepage.

Some final words

I will upload the most important and major versions here on CodeProject. For the latest unstable release, see the KeePass homepage: http://keepass.info/.

If you have some improvement ideas or you miss a feature, e-mail me.

That's it. I hope I was able to make your life a bit easier with this tool. :)