trunk/doc/winpt.texi

\input texinfo

@setfilename WinPT

This file describes the Windows Privacy Tray program and its main functions

Copyright (C) 2006 Timo Schulz
Version 1.2.0

@settitle WinPT - The Windows Privacy Tray; a free GPG front-end

@section Requirements for WinPT

First you need to have a working GnuPG 1.4 installtion on the machine you plan to install WinPT.
If you do not have GPG in your machine, please visit http://www.gnupg.org and download the latest
GPG version there. It comes with a graphical installer so there is no need to do the 
installation manually.

You need at least Windows 98/2K/XP, but Windows XP or better is recommend. The program also works
on NT/95/ME but there is no support for these OS versions any longer. Mainly because the OS
vendor also dropped support and no bug fixes will be provided any longer. 
And it is very likely that the program does not work optimal on such platforms.

@section A short Introduction

WinPT is a graphical GnuPG front-end which resides in the task bar. It is divided into several,
so-called, managers. There is a manager for the key(ring), for files and for smart cards. 
The aim of the program is to secure email communication and to perform file encryption and 
to allow an easy and user friendly way for key management.

@subsection What is GnuPG
GnuPG is a tool for secure communication and data storage. It can be used to encrypt data and
to create digital signatures. It includes an advanced key management facility and is compliant
with the proposed Internet standard as described in RFC2440.

@subsection The Web of Trust
For a detailled description of these and other GnuPG topics, I recommend the available literature
at http://www.gnupg.org. But at least a general overview should be given here.

The certification scheme of OpenPGP does not base on a hirachical approach. Instead it uses 
a combination of ownertrust and direct key certification. 
Here is an example with the imaginary persons called Alice, Bob, Carol and Dave.

Alice knows Bob and checked the fingerprint of Bob's key when he met him personally. 
Thus she knows that the key really belongs to its owner and he trusts Bob to certify other keys. 
Then she issued a signature on Bob's key. Bob knows Carol and also checked her identity.
Then he signed her key. Alice does not know Carol, but he knows Bob and Bob trusts Carol. 
And because Alice trusts Bob, at a level she decided before, he also trusts Carol. 
It's a transitiv relation. Dave is isolated and does not know anybody for the mentioned reasons, 
thus he is not in the WoT. Another very important point is, that the signer can decide, after the 
certification, how much he trusts the key owner to certify other keys.

It is very important to check the identify of a key owner. Mostly this is done by comparing the
fingerprint, which were submitted by phone or written down at a personal meeting, with the
fingerprint of the key in the keyring. Please bear in mind that anybody can create a key with an
email address and a specific name. 
Thus it is not recommend to sign keys without doing this check before!

The fingerprint of the key is hexadecial (160-bit) sequence divided into 10 groups of 4 hex
digits. You can get the fingerprint of a key by opening the key property dialog. There you can
mark the fingerprint and copy it to the clipboard. The fingerprint of a key can be compared
to human fingerprints, it is unique for each key.

Example: 1D75 8108 5BC9 D9FB E78B  2078 ED46 81C9 BF3D F9B4

It is a good idea to publish your fingerprint wherever possible.
For example via a business card or your website.

@section Installation of the Program

It is always recommend to use the latest version of the program. You can download it from 
http://wald.intevation.org/projects/winpt. Download the zip file with the binaries inside and
unpack them in a folder. All files need to be in the same folder, so if you change the folder do
not forget to move all files.
You should also download and verify the signature of the packet to make sure that the release is
really authentic and were not altered in any way.

To activate the program you just need to start WinPT.exe. You should now see a
little (golden key) icon in the taskbar which indicates that the program is running. 
If you want to quit the program, right click on the symbol and select "Exit".

Alternative, you may use one of the graphical GPG installers which are available on the internet.
I recommend to use Gpg4Win which includes a set of very useful privacy tools, beside WinPT and it
is very easy to use with an average size (~4MB). For non-German speaking users, I recommend the
light version because it does not contain the 2 German PDF manuals.

@subsection Configure the Program
After the installation not much of the default settings need to be changed. If you prefer a
special keyserver, it is propably a good idea to open the keyserver dialog and to set one of the
existing keyservers as the default or create a new entry and mark it as the new default. 
The default keyserver is subkeys.pgp.net, which is the best choice for most users.

@subsection The GPG Preference Dialog
In this dialog you can change your GPG config and customize its behaviour. Please be advised that
in most cases there is no need to overwrite the default GPG path settings.
There are three different paths available. First, the GPG home directory. The place where the
keyrings are stored and also the config files. The second path points directly to the gpg.exe.
The third is the path to the language files,
where you usually store your winpt.mo/gpg.mo files. These entries should be only changed when
really need and extra caution is needed because with wrong settings, WinPT will not be able to
work any longer!

The second part of the dialog is the "General GPG options" section. Here you can influence the
behaviour of some commands. If you do not know what they mean, it is safe not to change the
values and stick with the default ones.
For expert users, it is possible to set the signature class of issued key signatures and to set
an expiration date for key signatures or to specify an comment in armor files.
The "Encrypt to this key" might be useful for anybody who needs to decrypt mails or any data he
sent to a recipient. The field value should contain the key ID of the default key pair.

@subsection Preferences
In the WinPT preference dialog, the user can modify and/or disable the default options. For new
users it is suggested to leave the default values as they are, except when there are problems
related to the hotkeys.

To enable keyring backups, the user can either decide to use the GPG home directory as the backup
folder or any other folder. In the latter case, a folder needs to be chosen.
The program makes the backup before it terminates and thus it is very important that the keyrings 
are stil accessable at this moment. For example if you use an USB flash drive to store your keyrings, 
you should unplug it after the the icon disappeared at the task bar.
By default the secret keyring will not be backuped, if you wish that the secret keyring should be 
also backuped, and this usually means the backup folder cannot be accessed by other people, you need 
to mark "Backup includes secret keyring".

@subsection Getting the Source of the Program
As free software, according to the GNU General Public License, WinPT also offers the source code
for the program. It can be used for reviews, to compile your own binary and/or to modify and/or
redistribute it or just to learn how it works. The source is available at the same place you
downloaded the binary. If not, you should contact the author of the site.
The entire program can be build with free software; the default environment is a cross-compiler
hosted on a Linux box. All you need is the mingw32 packages, a working autoconf environment
and the libs WinPT depends on (currently gpgme and libgpg-error).
It is also possible to build the binary with cygwin/mingw32 on Windows but this environment is
not actively supported and propably needs adjustment of the source.


@section Native Language Support

The program has the ability to select different languages to provide dialogs and error messages
in the native language of the user. Currently German, Japanese, Portuguese (Brazil) and Slovak.
When WinPT has been installed via a graphical installer, for example Gpg4Win, the language was 
automatically selected based on the locale Windows environment. If the stand-alone binary was 
downloaded, WinPT offers at the first start to select a language, based on the .mo file it 
founded in the current directory. 
Otherwise the user needs to perform the following steps. The WinPT ZIP archive contains various 
.mo files (de.mo, jp.mo, sk.mo) and the user needs to find his native language, if available and
rename the file to "winpt.mo". For example, if the user prefers German, "de.mo" -> "winpt.mo".
Now the user needs to save the locale dir, where the winpt.mo is stored, in the GPG preference dialog.

@section The First Start

This section is only important for people who never installed and/or used WinPT before and thus
no keyrings are available.

When the program is started the first time, it offers two choices. The one is to generate a key
pair and the other is to copy existing GPG keyrings into the current installation.

We assume the user will select the first entry.

Now a new dialog is shown which requests some information from the user to allow a meaningful
association between the key and the user. If the user prefer RSA keys, the check box should be
marked.
But this is a decision of personal taste and does not influence the security or anything else.
If the entered data is OK, WinPT then generates a new key pair. As long as this step takes, a
progress dialog is shown to indicate the enduring process. When the generation of the keypair is
done, WinPT offers the chance to backup the existing keyrings. 
This is definitely an important decision because if the keyring will get corrupted or lost, there
is no way to recover the encrypted data. That is why it is also important to store the backup, at
least of the secret keyring, at a @strong{safe} place.

@subsection Use existing Keyrings and/or Keys
If you already have a valid OpenPGP key pair and you do not want to generate a new key pair, you 
should select the second choice at the first start. Then the program will copy your existing keyrings
to the new home directory. Please bear in mind that you need to set the ownertrust manually for each
imported key. You can skip this step if you exported the ownertrust manually to a file, but because 
this is a step for experienced users it is not described here. The most important step is, to set 
your own key to ultimate ownertrust after import.

If you have other OpenPGP programs and you wish to use the keys from this application, it is a good 
idea to select all keys you want to use and to export them into a single file. Then open the WinPT 
Key Manager and drag the file into the Key Manager window. 

@section The Passphrase for the Secret Key

First a short explaination what passphrase is. A passphrase is like a password but usually
longer, maybe a sentence, which can consists of any 7-bit ASCII characters. It is used to protect
your secret key and thus it is very import to chose a secure passphrase. If your computer, and
thus the secret key, were stolen and an attacker can guess your passphrase he is able to decrypt
all your data and to create signatures in your name! A good passphrase is difficult to guess but
easy to remember and should be at least 10 characters long.
An easy way to generate a strong passphrase is to use a sentence only you know but you can easily
remind and then take the first letter of each word, plus some special characters and maybe even
some intentionally made spelling mistakes. 

Example: Row - row - row your boat, gently down the stream
Passphrase: "R - r - ryb,gdts"

Never write down your passphrase or share it among other people!

@section Keyserver Access

An easy way to retrieve keys is the keyserver. You can think of it like a huge database with a
lot of keys as its content. It is possible to search keys by a pattern, a keyid or even a
fingerprint.
WinPT allows to access different kind of keyservers. For example LDAP, HKP, Finger and HTTP. 
But the focus will be set on HKP because this is the common case.

In some situations WinPT asks the user whether to retrieve keys automatically. One example is the
signature verification when the key that issued the signature was not found in the keyring.

The main keyserver dialog allows to fetch one or more keys directly or to search for a given pattern.

@subsection Retrieve a key by Key ID
The best way to fetch a key from the server is by the key ID.
Just enter the key ID, it is a good idea to prefix it with 0x, and click the "Receive" button.

An example:

pattern: 0xBF3DF9B4

[Receive]


@subsection Retrieve a key by its email address
If you only know the email address from your partner, you can enter it instead of the key ID. 
It is unlikely but possible that there are more keys with the same address. In this situation,
WinPT will warn you that multiple keys were imported. The difference to the search function is,
that the keys were dirctly fetched and not displayed as a key result list.


An example:

pattern: name_of_friend@@gmx.net

[Receive]


@subsection Search for a key by pattern
If you want to communicate with a new mail partner and you are not sure about the key ID, it can
be useful to search for his email address. This address is considered as quite unique. 
Not all keyserver support this query mode, so if you get an error please use subkeys.pgp.net.

An example:

pattern: winpt@@windows-privacy-tray.com

[Search]

Now a dialog is opened with a list of all keys which matched the search string. If the name
@strong{and} the email address is known, the matching key should be selected and "Receive"
should be clicked. Then the key will be downloaded and added to your keyring. Now you can encrypt
data with this key, for example an email.


@subsection Sending a Key to the Keyserver
After you generated a new key pair, it is a good idea to send your key to the keyserver to make
it available for other users. If you issue a signature, the key ID is part of the signature and
people can  automatically retrieve your key when they try to verify the signature.

Actually, the action is performed in the Key Manager and not in the keyserver dialog. Just open
the Key Manager, select the key you want to send right-click on it and chose "Send to Keyserver"
in the popup menu. Then a message box with the result is shown.

@subsection Add, Delete or Edit a Keyserver Entry
The keyserver dialog allow to change the existing keyserver entries, to delete them or to add new
entries. Just right click on a selected item and a popup menu will be 
shown with ("Edit", "Remove" and "New").

@section Using the Clipboard

A major aim from the first day was, that the program does not depend on a special mailer client.
For this reason it uses the clipboard to encrypt and/or sign data.
For the examples, let's assume that you want to write a new mail or that you received a mail
protected by GnuPG.

@subsection The Clipboard Editor
This dialog allows it to modify the clipboard contents directly and/or to display the contents of
the clipboard. It is also possible to load a text file into the clipboard or store the contents
into a file. For the convenience, the dialog also allows to encrypt and/or decrypt clipboard data.

@subsection Encrypt Data in the Clipboard
Just copy the text from the mailer window into the clipboard. This is usually done by CTRL+C,
make sure you really selected all portions of the text. Then right-click on the tray icon and
select Clipboard->Encryption. Now a dialog is shown to select the recipients. This means you need
to select all keys which should be able to decrypt the mail. Confirm with "OK". GnuPG now
encrypts the data with the selected recipients. At the end a message box with the result is
shown. Now the clipboard should  contain the encrypted data. Just paste it into the mailer window.
The output should contain a header and a footer "BEGIN PGP MESSAGE" and "END PGP MESSAGE.

@subsection Decrypt/Verify Data from the Clipboard
The most common case is propably that you got a signed email and now you want to verify it. For
this procedure, you have to copy the entire signature in the clipboard. The easiest way is to
use CTRL+A and CTRL+C, then all available text will be copied. WinPT (GnuPG) is smart enough to
figure out the signature related data. Now go to the taskbar, display the popup menu and select
Clipboard->Decrypt/Verify. Now a new dialog, the verify dialog, should be available on screen
with all information about the signature. For example who is the signer, when was it signed how
much do you try this key and what was signed and most important, the status of it (is the
signature good or BAD).
A special case is when you don't have the public key to verify the signature, if this happens
WinPT offers to download the key from the default keyserver. If the key was not found, the
procedure is aborted because without the key the sig cannot bed checked.

@subsection Sign the Clipboard
We assume that text that shall be signed is already in the clipboard. If not, select the text you
want to sign and copy with via CTRL+C in the clipboard. Now go to the taskbar and open the peopup
menu, Clipboard->Sign. If you just have one secret key, the passphrase dialog will be automatically shown.
All you need is to enter your passphrase and confirm. In case of more available secret keys, a
list with all keys is shown and you can select which key shall be used for signing.
The output is always a cleartext signature which is in text format. Do not try to sign binary
clipboard data, the result would be unpredictable and not readable by human beings.

@section The Current Window Support
Compared to the clipboard mode, the CWS mode has some advantages. Let us assume that you want to
extract text from an editor window. With the CWS mode, the program automatically tries to focus
the window to select the text and to copy it to the clipboard and execute the 
selected command (Sign, Encrypt, Decrypt) and pastes back the GPG data to the window. 
No manual user interaction is needed. Except this different behaviour, it is very likewise to the
clipboard mode and thus we do not describe each command again.

But due to the nature of this mode, it is possible that some kind of windows are not supported. 
Which means that the program cannot extract the text from the window. There is nothing we can do 
about it, because it depends on the application itself how it reacts on certain Window messages. 
But all windows which support the default copy/paste/select all commands should make no problems.

@section The Key Manager

This part of the program is propably most important for many users. It contains function to
manage your keyring and to perform actions which are required and/or useful in the OpenPGP environment.

@subsection Tips

@itemize @bullet

@item
If you want to start the Key Manager directly, you can create a batch
file with "winpt.exe --keymanager". This way you do not have to go to
the task bar enable the icon and click on the Key Manager entry in the menu.

@item
If you want to import quickly a key from a into the keyring, just drag and drop the file into the
Key Manager window. Then the import procedure will be automatically started.

@item
Key which were fetched from keyservers often contain a lot of, maybe obsolete, self signatures,
if you want to get rid of them you can use the Key Edit->Clean feature. Just start the edit
dialog and select the clean command. That's it.

@item
The keyserver dialog does not allow to import a key directly via an URL, as an alternative you
may use the "Import HTTP..." feature in the Key Manager. With it you can directly fetch keys
from the web (Example: http://www.users.my-isp.de/~joe/gpg-keys.asc).

@item
To customize the parameters of the generated key, you can use the expert key generation. 
It allows you to set the public key algorithm and/or the size of the key directly.

@item
Most of the list view based dialogs allow to use the right mouse button, to show popup menus with
available commands.

@end itemize

@subsection Create a Revocation Certificate
It is very important to do this step early as possible. With this certificate, you can revoke
your entire key. The reason for this can be for example, that your key is no longer used or even
compromised.
After you generated the revocation cert, you should move it to a secure place because anybody who
gets access to it, can render your key unuseable.

Just right-click on your key and select "Revoke Cert". If you do this step directly after key
generation, there is no need to change the default values. Just select a file name and enter the
passphrase. The program issues a warning which should be read carefully.

@subsection Adding a new Secondary Key
For most users the existing keys in the key pair are enough and no extra key is needed. But there
are some exceptions.

@itemize @bullet

@item
The primary key has no secondary key and the primary key is not able to encrypt data. In this
case it can be a good idea to add a secondary encryption key.

@item
A lot of people use secondary encryption keys with an expiration date. Usually the key is valid
for 1-2 years. After the key is expired, a new key is needed in order to encrypt data.

@end itemize

What kind of public key algorithm should be selected is a matter of taste. RSA and ElGamal are
both capable for encryption. For most users it's a good idea to let the program chose the key
size (in bits). The default settings should be secure enough for most purposes.

@subsection Adding a new User ID
If you got a new email account, it's propably a good idea to add these new account to your key
also. For example:

A new account was registed at gmail.com (john.doo@@gmail.com). 
Then you should create a new user ID with the following fields:

name: John Doo

email: john.doo@@gmail.com

comment: (optional)

Now email programs are able to associate this address with your key when somebody wants to send
you a protected mail to this account.

@subsection Adding a new Photographic ID
With this function you can add a photo to your public. It will be displayed in the key property
dialog.

You just need to select a JPEG file which contains the photo and enter your passphrase and
confirm with OK. Please read the note in the dialog carefully to make sure the photo has a proper
size (file, height and weight).

@subsection Adding a new Designated Revoker
If you want to allow another key to revoke your own key, this might be useful if you lost your
secret or a simliar situation, you can use this function to add a designated revoker to your key.

All you need to do is to select the key you want to add as a desig revoker. But please bear in
mind that this procedure cannot be undone and that this person really has the power to make your
public key unuseable. You really should trust the selected key, in case it is not a key owned by yourself.

@subsection Export a Public Key
There are several reason why to export a public key and there are also several ways to do it. If
you want to send the key directly to a mail recipient, you can select the key, right-click,
and select "Send Key to Mail Recipient". As an alternative, you can also export it to the
clipboard or to a file. To export a key to the clipboard, you can select "Copy key to Clipboard"
in the popup menu of the selected key. To export it to a file, you need to select the menu "Key"
and then "Export...". The program will automatically suggest a name for the output.

@subsection Export your Secret Key
This command should be used with caution because it exports your secret key. Please bear in mind
that you should never export your key to a place where it can be accessed by others. 
An USB stick or a likewise mobile storage device should be used for the export.

@subsection Import a Public Key
Similar to the key import, the import of a key can be done in several ways. First, let's assume
you got a mail with an OpenPGP key included as inline text. Then you can use the current window
feature and "Decrypt/Verify" to import the key. Alternative you also may use the clipboard. 
To achieve this, you first need to select the entire key (CTRL+A) and then copy it to the
clipboard (CTRL+C), then use the Key Manager (Edit->Paste) to import it. If the key is stored as
an attachment, or you want to import a key from a file in general, just drag the file and drop it
into the Key Manager window or use "Key" -> "Import...".

@subsection Sign a Public Key
If you verified that a key really belongs to its owner, you should sign the key to integrate it
into your Web of Trust and also to mark the key as valid in your keyring. Do not sign a key you
just got via email with the request to sign it. Anybody can create a key with your (or better ANY) name, 
these information are no hint to whom the key really belongs. You can check a key 
by meeting or calling the key owner and verify the key fingerprint of the key with the one
published by the key owner. Additional checks should be to watch at his driver license or the
identity card to make sure that name of the key matches the name of the key owner. After this
procedure is done, you can open the Key Manager, select the right key and either use the context
menu "Sign Key" or use the toolbar button.

The next dialog will summarize the key information and some additional options. For example if
the signature should be local or exportable. Local means the signature will be stripped if you
export the key and no one else except you can use it to calculate the validity. If you mark the
signature exportable, any other user can see and use it. Now you can select the key you want to
use to sign and enter the passphrase. Confirm with "OK" and the key will be signed.  Now the validity 
of the new key is "Full". It is propably a good idea to set the ownertrust of the key. 
For a detailled description, see the chapter "Key Ownertrust".

@subsection Key Ownertrust
First we should explain what the ownertrust of a key is. The ownertrust is a measurement how much
you trust somebody to certify and check keys of other people. For example, if you know that Bob
is really the owner of the key, you should sign it. But he is also known to sign other keys
without checking the idenity of the other key owner. Values for the ownertrust are 
1) Don't Know 2) Don't Trust 3) Marginal 4) Full
and thus you should propably use an ownertrust value like "Marginal". But this is a personal
decision and stored in a separate file and never exported with the public keys. For further
information, please take a look into the GNU Privacy Handbook.
Just a last work on Key Pairs, they are automatically marked as "Ultimate" because the key
belongs to you and you trust it implicit.

@subsection List Signatures
This dialog contains a list of all signatures of the selected key. The basic dialog, the tree
based version, just shows signatures when the issuer key is in the public keyring. A double click
opens the signature property dialog which contains detailled description about the selected
signature. A dialog which is useful for people who wants to get all information about the key
signatures, can click on the "Edit.." button.

@subsection Copy Key Information to the Clipboard
Often it is useful to copy parts of the user ID to the clipboard. One example is that you want to
send an email to the key owner or that you want to search the key by the email address or you
want to copy the fingerprint to the clipboard to paste it somewhere else.
This command is available in the popup menu (right click).

@subsection Delete one or more Keys
To delete a key, or more than one key, you just need to select the keys in the Key Manager and
either select "Delete" or use the toolbar button.
Be careful if you delete a key pair, because you will not be able to decrypt and/or sign data any
longer. In any case you should have a backup of your key pair at a safe place.

@subsection Re-verify Signatures
After you refreshed or imported a lot of new keys, either from a file or the keyserver, it is a
good idea to re-verify the signature in the keyring. This speeds up listing operations.

@subsection Refresh one or more Public Keys from the Keyserver
From time to time it can be useful to refresh keys from the keyring. The reason for this is,
that the key might contain new subkeys, user IDs and or new signatures. It is also possible
that the expiration date of a key has been updated or other preferences were changed. And
maybe even the worst case, that a key has been compromised and is now revoked.
If you want to update a single key, select it and right click on it. Then select the item
"Refresh from the Keyserver" in the popup menu. If you do not select any key, the Key Manager
assumes that you want to refresh all keys in the keyring. Please bear in mind that this
can be a lengthy process if you have a lot of keys in your keyring.

@subsection WinPT Website
If you want to check for updates or general information about the Windows Privacy Tray program,
you can select this menu item.
The WWW webite of WinPT will be loaded in the default browser.
If you want to visit the project website directly, select the "Project Website" entry.

@subsection The Key Edit Dialog
For the average GPG user, the popup menu of the Key Manager contains all command to manage your
keys. For example to add a key/userid/revoker/photo, just right click on the click and select the
command from the "Add" submenu.
But for advanced users, this dialog contain a lot of extra commands to customize your key.

The main dialog contains a list of all keys in the first list view box and all user IDs in the
second list view box. The help button gives you a short hint about each command and what it does.
For example you can set the primary user ID via the "primary" command or with "deluid" you can
delete the selected user ID. Please always bear in mind, that most keyserver are not able to
remove user IDs in its database so if another user fetch your 'updated' key from the keyserver
the user ID might be still part of the key. If you want to make an user ID unuseable, you should
revoke it. This is also possible with this dialog.

@subsection Update your Preferences in the Key Manager
To avoid that the user needs detour to select the taskbar icon, click on it, etc., all
preferences can be changed in the Key Manager via the Edit->Preferences... menu.

@section The File Manager

@subsection Introduction
The File Manager is no replacement for an Explorer Extension. If you secure your files frequently
and you want to do this fast and easy, I suggest to install GPGee. It is a program which
integrates itself into the explorer and provide menu entries in the context menu of files and
directory. But the File Manager can be very useful if you just want to decrypt and/or encrypt
some files without additional programs. You can find the File Manager via the symbol in the
taskbar, right click and then "File Manager".

@subsection An Overview of the GUI
First there are different ways to add (open) files in the Key Manager. The easiest way is to use
drag and drop to add files into the File Manager. Just drag a file from the explorer and drop it
into the File Manager window. The second way is to use File->Open. A dialog opens which is common
for all "File Open" operations in most Windows application. Now you can select one or more files
and confirm. The files will be automatically added to the File Manager window. The main window
consists of a listview with three rows. 

The first row is the status of the file. It can be "ENCRYPTED", "SIGNED", "PUBKEY", "SECKEY",
"SIG" or "UNKNOWN". Dependent on the file status, the File Manager offers different choices. 
For example "SIG" enables the verify options in the (popup) menu. "UNKNOWN" is the default for
all plaintext files.
The second row is the file name. And the last row is the status of the operation. It can be
either "", "SUCCESS" or "FAILED". An empty status means no operation was started yet. FAILED
indicates that the  GnuPG operation failed. In this case an error message was issued before.

Now it follows an example:
We assume that user wants to encrypt "c:\My Ideas\GPG GUI.txt". Drag the file from the Explorer
and drop it into the open File Manager, the main window. The file will be added and recognized
as "UNKNOWN". Now we select the file and right click, a popup menu is shown and we select
"Encrypt". An new dialog is opened which looks similar to the Clipboard Encryption dialog. 
Just select the recipients and confirm. In contrast to clipboard encryption, file encryption
offers some more extra options. They are described later. And hour glass will be shown as long as
GnuPG takes to encrypt the file. When the procedure is done, the third row should be change
to "SUCCESS" and the first row to "ENCRYPTED".

@subsection Verify Detached Signatures
Most of the signature are detached, which means that the signature is separated from the data. 
Usually you need to verify a detached signature when you have downloaded a software package or 
an update of it. The steps to verify such a signature are easy. Just open the File Manager and 
drag the detached signature in the File Manager window.
Now select the signature and select "Verify" either via the popup menu or the File menu.
In most cases you propably need to download the verification key, before you can verify the signature.

@subsection General Options
Now we describe the general options which are possible in some File Manager dialogs.

@itemize

@item Text Output
When this option is checked, the output will be encoded in ASCII armor. This can be useful if the
file should be transfered via email. The size of the output file is larger than the usual binary
output.

@item Wipe Original
If this option is checked, the original file will be deleted after successfull encryption. 
This can be useful if data should not be available in plaintext any longer on a machine.

@end itemize


@section A short Note about Cryptographic Issues

WinPT itself does not perform any real encryption, signing or decryption. Instead it uses 
GPG as the backend program which provides all kind of cryptographic code to perform the 
needed operations. 

The default values WinPT uses for key sizes, should be sufficient for personal and commercial 
security for the next years. If you are concerned about the default values, you can always use 
the expert key generation to make your own decision. GPG also provides
default values for symmetric cipher preferences. By default, the AES (Advanced Encryption Standard) 
is used which provides a very good security. You can manually modify your key preferences, this 
includes cipher, hash, and compression but usually this is not necessary and also can do harm if 
you use algorithms which are not very widespread among other OpenPGP programs.

@section WinPT and Personal Firewalls

Because the program uses a global hook to remember the last active current window, it might be 
possible that Firewalls warn that the process contains a global hook which is a potential 
security risk. In some cases, there might be even a warning that key logging is possible. 
This is a false alarm because the hook provided by the program, a CTB (Computer Based Training) 
hook, can be only used to save handles of newly created windows, or windows which are
activated or in case of a focus change. Details can be found in the source code of the program 
or additional information about the CTB hook at msdn.microsoft.com

To provide access to keyservers and to download HTTP keys, the program
needs to be able to make outbound connections to the following ports: 80 (http), 11371 (keyserver)

@subsection Using a HTTP Proxy
If you are behind a firewall and you have no chance make a connection to a keyserver, maybe 
because of a policy, you can use a http proxy for outbound connections. Open the Keyserver dialog 
and click on the button "Change Proxy". A new dialog opens where you can enter the proxy specific 
host name and ports. If the proxy requires authentication, you also have to provide your user name
and your password. Please bear in mind that only a base64 authentication is supported and no other 
proxy types (SOCKS for example) can be used.


@section Reporting a Problem (Bug) or a Feature Request

For the case that you have problems with the program, that includes crashes or or the handling,
please first check the forum at http://wald.intevation.org to see if someone else reported and/or
wrote about the issue. It is possible that the issue is already solved/answered in the forum.
Plus all other users can benefit of it because maybe another person has the same problem and then
he can check the forum and will find the answer.

Feature requests can be submitted at the same site in a different tab (Tracker->Feature Request).
There is no guarantee that the request will be implemented in the next version. The reason is,
that other issues might be more important or that the request must be first discussed with other
developers. But each request will be considered.

For the case that you found a bug, it is very important to provide much details as possible to
allow the developers to track down the problem and to fix it easily. Please do not forgot to be
precise as possible and the best idea is to provide a step-by-step text to reproduce the problem.

@section Problem with the Program or an unexpected Behaviour

First let me say that it is very important always to use the newest version. Each new version
contains bug fixes and might also fix usability issues. This is also valid for GPG, WinPT
checks that the minimum GPG version is available but even so it is important and often useful to
have the newest GPG version if this is possible.

But sometimes the problem is not the software itself, but the software which was involved to
transfer the data. Here are some examples of what could happen:

- The downloaded file could be broken (FTP ascii->binary issue) and thus WinPT is unable to
  verify the signature. In this case you should download the file again.

- A mailer broke the signature because the line endings were altered or the mail text was wrapped
  after the signature was issued. There is no solution to this problem, except to use
  a smart Mail Client.

- A public key (file or clipboard) will not be recognized but the data should definitely contain
  one or more keys. Sometimes line endings are messed up or white spaces were removed. In
  this case GPG/WinPT is not able to detect when the data begins and the header section starts.
  You can use the clipboard editor to see if the ascii armor is broken. If this happened, the 
  file must be repaired manually or should be sent again.

- WinPT reports that the key could not be imported because of missing self signature or a
  likewise message. To make sure that the receiver can really verify the key belongs to its
  owner, the key carries a self signature which can be checked by anybody. Some PGP 2.6 version
  do not issue this self signature and some other PGP versions might be also able to
  supress its generation. Such a key cannot be used, even if the import were forced. The solution
  to this problem is easy but sometimes not possible. Ask the key issuer to self sign his key and
  to upload it to the keyserver or send it again.
  But sometimes companies have a policy and thus newly generated keys are not self signed. I do
  not know what to do in this case except for asking if it would be possible to sign a copy of
  the key.

- You received a message from a user which uses PGP and WinPT/GPG will not be able to decrypt it.
  First let me say that this should happen very seldom with newer (PGP >= 7) versions of PGP.
  The reason could be, that IDEA has been used. A patented Cipher which is not included in GPG.
  GPG will not be able to decrypt the data because it has been ciphered with IDEA. There is no
  solution for this problem, except to use the IDEA plug-in. But be advised that the IDEA
  algorithm is only free for private use and NOT for commercial mails.

  Another problem could be, that your files cannot be automatically decrypted by the receiver
  (who uses PGP) because the file extension of it is .GPG. You can solve this problem by changing
  the default extension in the WinPT preferences from .GPG to .PGP.

  To minimize the change of problems when you communicate with a PGP user, you can add "pgp8" or
  "pgp7" to your gpg.conf. This can be done via the Key Manager
  ->Edit->Preferences...->GPG Config Preferences.


@section How can I help the Project

There are several ways to help the project. For example you could provide (or work on) the
existing documentation or write new docs. You could translate WinPT into a new language or
maintain an existing language file. Of course it is also possible to contribute code or to
become part of the WinPT developer crew. 

@subsection What I need for Development
First, you need a Windows C-compiler and knowledge how to use the tools and the Win32 API. There
is no need to use MS-Visual C,  you can use Ming-W32 (gcc) and a free IDE to hack some code.
The default building environment is a mingw32 hosted on Linux and it produces W32 executables.

If you plan to contribute some code or to work on an item from the TODO file, please contact me
first to make sure no one else is working on it and that and we can discuss the details.

@section Closing Words
Please remember that currently the core WinPT crew is just me and thus it might take some time to
respond to forum messages, and mails. If my spare time allows it, I try to respond quick as
possible. But as a free software project, I do most coding in my spare time and I can't guarantee
anything. If you need commercial support for WinPT or GPG in general, 
please contact g10 Code GmbH.

@bye