INTRODUCTION
============

KeePT is a plugin which combines KeePass and WinPT. But what is it for? I can 
just use KeePass's hot key functionality to pass the GPG password. But my reason 
is different: I hate startup up dozens of application which all occupy an icon 
in the system tray. This is even more true when I do not use the applications 
regularly. This was already the reason for the PuttyAgent plugin: No need to 
start both KeePass and pageant.exe. 

The same is true here: The main and unspectacular purpose of this plugin is to 
start WinPT (and hence GPG) from within KeePass. The minor purpose is to pass 
the GPG password from KeePass to WinPT. 

This plugin *requires* WinPT. At first, I wanted to compile WinPT into a DLL, 
just as I did it for PuttyAgent. But after spending hours in trying to compile 
the old WinPT code I gave up and decided to "control" the pre-compiled binary. 
This has another advantage: The plugin occupies only 80kB (written purely in C++ 
with WinAPI) whereas the whole WinPT (occupying 1-2MB!) is only loaded when 
needed.

Disclaimer: This plugin is beta and not tested by anybody other than me, so 
please keep backups of your files. Please try it out and contact me in case of 
problems in order to improve this plugin.

How does this plugin work?
==========================

Basically, it displays WinPT's tray menu in the tray menu of KeePass 
("KeePT...") and in the Tools menu. The menu is directly read form WinPT.exe. 
After selecting a menu entry, the plugin creates a new thread in which WinPT is 
started and the specific action launched. 

KeePT uses LoadLibrary on WinPT.exe to read the menu. The path to WinPT.exe is 
determined as follows: For the portable version of GnuPT, the WinPT.exe is 
searched in the subdirectory "WinPT" of GnuPT-Portable.exe. If the standard 
WinPT.exe shall be used, KeePT uses the path from the settings directly. If the 
path is not set at all, KeePT uses LoadLibrary on either WinPT.exe or 
WinPT\WinPT.exe, depending on the portable settig. This means that WinPT.exe is 
searched either in the current folder or in the path. 


Starting and exiting WinPT
--------------------------

The plugin first searches for an existing WinPT instance and sends the commands 
to this instance. If no instance is running, the plugin uses CreateProcess to 
execute WinPT. There are two ways to configure KeePT: To use the portable 
version of GnuPT or to use WinPT.exe directly. 

The setting can be changed in the plugin settings:

[x] Use WinPT (start WinPT.exe)
[ ] Use WinPT portable (start GnuPT-Portable.exe -WinPT)

The path to the exe file (either WinPT.exe or GnuPT-Portable.exe, depending on 
the settings above) can be set in the plugin settings. 

If the plugin started WinPT, there are two options: Either WinPT keeps running
or the plugin waits until all dialogs from WinPT are closed and terminates the
application again. This (default) behavior can be set in the settings by:

[x] Close WinPT.exe if it was started by us


Using WinPT hot keys
--------------------

WinPT provides the option to set hot keys in the settings menu. KeePT can try to 
register these hot keys in the plugin settings: 

[x] Try to register WinPT's global hot keys 

When this option is set, the plugin will read out the hot key configuration by 
WinPT from the registry, register the hot keys and pass them to WinPT (the same 
way as the action would be selected from the tray menu). Before starting WinPT, 
the hot keys are unregistered, such that they are registered by WinPT. This 
means: As soon as WinPT.exe is started by the plugin, the hot keys are processed 
by WinPT itself.

Note 1: When the option "Close WinPT.exe if it was started by us" is not used, 
this option should be avoided as well, since both WinPT and KeePT will try to 
register the hot keys. KeePT will display an error message in that the keys are 
already registered in this case.

Note 2: This option will not work with the portable version of GnuPT since the
hot keys are not permanently stored in the registry in this case.

Note 3: The CTRL + ALT + F key (flushing the passphrase) is not supported by
KeePT since WinPT does not provide a WM_COMMAND for that.

Passing the passphrase from KeePass to WinPT
--------------------------------------------

In order to support passing the passphrase, the plugin injects itself into the 
running WinPT instance and overwrites the DialogBox API function which is used 
by WinPT to display the password dialog. In this case, a request is sent to the 
plugin and the plugin searches the KeePass database for an entry matching the 
key id. If it is found, the password is passed to WinPT. If there is an error, 
the default password dialog is displayed. 

Note on security: The passphrase is not passed by WM_COPYDATA (only the key id) 
but by using shared memory. The memory for the passphrase is memset by 0x00 as 
soon as the password is not needed any more. 

When the database is locked, the plugin attempts to unlock the workspace by 
displaying the master password dialog. 

There might be cases when injecting the DLL into WinPT does not work. In this 
case, the plugin works except for passing the passphrase and an error message is 
displayed. 

The GPG passphrase is found in the database by looking at the Notes-entry and 
finding a matching 

GPG-Key-ID: 0x12345678 

entry where 0x12345678 represents the key id for the private key. The key id can 
be found in WinPT using the key manager column "Key-ID" or by decrypting a 
message with WinPT. WinPT then displays the key id which is used to decrypt this 
message. 

Using GnuPT-Portable
====================

When using Gnu-PT portable, it is strongly advised, to disable the 
startup message, i.e., in GnuPT-Portable.ini:

Message=0

The reason is: The plugin executes GnuPT-Portable.exe with -WinPT as argument
and waits for 5 seconds (using FindWindow on the WinPT window) to WinPT to start
up.

INSTALL
=======

Just copy the files to the program directory of KeePass and restart KeePass. The 
plugin can be configured in the plugin settings. 

HISTORY
=======

v1.2 beta:
- Automatic configuration dialog when WinPT not found/unsupported
- Configure plugin in tray menu
- Increased security for password transfer:
  - Use of memory mapped files
  - Prevent Windows from swap out the password's page
  - Check is SID matches
- Bug: CRT library mismatch could crash WinPT -> plugin uses WinPT's password
  dialog for memory allocation
- Many minor changes
- Increased timeouts

v1.1 beta:
- Fix: Did not set CTRL+ALT+F hot key correctly
- Fix: WinPT does not use KeePass when no file loaded at all
- Fix: Added menu icon
- Feature: Support for GnuPT-Portable

v1.0:
- First release


Niki Hammler,
niki@hammler.net
niki.hammler.net


