PuttyAgent plugin for KeePass by Nikolaus Hammler

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

The PuttyAgent plugin adds SSH agent support to KeePass. It is derived
from PuTTY's Pageant.

The plugin works as follows: Just attach any *.ppk file to a password
entry. In case that the ppk-file is password-protected, add the password
to the password field. The key is first tried without a password and
afterwards with the password from the password field.

All *.ppk files found within KeePass are automatically served by the
plugin while the workspace is not locked. When locking the database,
all loaded keys are discarded.

The key list is updated when opening the database or unlocking the
workspace or after saving the database. Therefore you have to save the database
first for the changes to take effect after removing/adding key files
to KeePass.

The current list of served keys can be viewed through

  Extras -> PuttyAgent -> Show Keys

When there is a signing request and the workspace is not locked (i.e.
the keys are loaded), a balloon is displayed.

If the workspace is locked, a request is made to unlock the workspace.
In the default setting, a balloon is displayed, asking
the user to click on it. After clicking on it, the master password dialog
appears to unlock the window. In case of success, the signing request is
served.

The balloon is displayed with a timeout of 5 seconds; however, depending
on the Windows settings, this might be different.

The plugin waits for 40 seconds after displaying the balloon until the
workspace can be unlocked successfully (or the user actively cancels
unlocking the workspace). After this timeout, the workspace stays locked
and the signing request is not served.

The plugin settings allow to configure when the balloon is displayed.
When the balloon for unlocking the workspace is disabled, the master password
dialog is shown immideately.

Please note that there can only be one agent running at the same time.
Therefore it is not possible to use this plugin and pageant.exe at the
same time and/or with multiple KeePass instances.

CYGWIN/MSYS OPENSSH AGENT SUPPORT
=================================

Starting with version 3, this plugin also adds support for openssh included in
cygwin and msys. In contrast to PuTTY, where the message exchange is based on
a mapped file and WM_COPYDATA, these applications use the cygwin emulation of
a UNIX domain socket.

In order to use this functionality, enable it in the plugin settings (disabled
by default) and set a socket path. The file must not exist and the directory
must be writeable for KeePass.exe.

After configuration, check if the file indeed exists.

Go into the control panel, "User Accounts" and select "Change my environment
variables". Then add a user variable SSH_AUTH_SOCK and set it to the path given
in the plugin settings.

Note that a windows path is just fine; both Cygwin and MSYS ssh versions will
be able to find it.

After that, just open a cygwin/MSYS window and enter 

     echo $SSH_AUTH_SOCK
     ls -la $SSH_AUTH_SOCK

to check if it is set and points to the correct file.

ADVANCED USAGE
==============

The plugin can be controlled by an external program by using the agent
protocol. It is possible to list, add or remove keys by an external
application.

Most notably, the original pageant.exe can be used to load additional
keys to the plugin:

  pageant.exe new-key.ppk

However, currently these keys are discarded when key update occurs,
that is, when locking workspace, closing or saving the database file.

Currently I only need keys within KeePass therefore I did not implement
advanced features. If you do, please drop me a mail. If I have time I
may add functionality.

INSTALL
=======

Just copy the files to the program directory of KeePass and restart KeePass.

HISTORY
=======

v1.0:
- Initial release

v2.0:
- Complete internal redesign (see ARCHITECTURE.txt)
- Uses own thread with window to avoid blocking
- use of balloons

v2.1:
- Added check for security descriptor when connecting
  (only processes from same user are allowed to use agent)

v2.2:
- Updated to Putty sources 0.63
- Added enable/disable functionality for agent in menu

v2.3:
- enable/disable functionality does not make messages boxes (no confirmations)
- Added settings dialog with option to immideately show unlock dialog
  (do not display a balloon for request)

v2.3.1:
- Bugfix: Start of Agent was sometimes not detected. Added an event and wait
  for that. Enhanced reliability of logic.
- Removed info about requesting client program (cannot be accurately detected)

v2.3.2:
- Added more reliable info about requesting client program using code by
  Zoltan Csizmadia, zoltan_csizmadia@yahoo.com
  Balloon displays full path to module requested the access
- All balloons can be configured

v2.3.3:
- Corrected typos

v3.0:
- Added cygwin/msys openssh support
- Minor internal revisions along with that

TO BE DONE
==========

The following things needs to be done:
- Check return value of SetWindowLongPtr
- Additional check version of shellapi to make sure if displaying
  the balloon is successful
- Do the locking mechanisms in CKeyHandler more specific
- Adapt to new plugin interface (as soon as it is released).
  E.g., take HWND from g_pAPI
- Improve restoring the previously active window. Not, most of
  the time, it only flashes in the task bar.
- Consistent/configurable timeouts
- Loading of external keys

This plugin contains "SystemInfo.cpp" by Zoltan Csizmadia,
zoltan_csizmadia@yahoo.com.
This code is used to enumerate all "section" handles on the system.
The handle list is enumerated to match the PageantRequestXXXX name which
belongs to the application requesting the public key.

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