Annotation of /trunk/README

                        WinPT - The Windows Privacy Tray
                        =================================


Bugs and Improvements
---------------------

I have tried to thoroughly test this program, but if you've found a bug,
please send me a message with a full error description or go directly
to http://wald.intevation.org and use the WinPT bug tracking system.

Please include as much detail as possible including OS version, WinPT
version, and GPG version in use. Please summarize your gpg configuration
and describe any special programs or configurations on your machine. 

I try to fix bugs as quickly as possible and will upload all updates to
http://wald.intevation.org/projects/winpt


Legacy Windows versions
-----------------------

I know a lot of people still user old versions of WinPT but it is very
hard to test the code on all these platforms and thus I decided to
obsolete the support for these OS versions: Win95, WinME/98. The code
works on 98/ME without known limitations but if you will encounter
a serious problem, I doubt I can fix it without having this OS and
this is the major problem! It is likewise with older NT based systems
like NT4 and, with each new year, Win2K.


What is WinPT?
--------------

WinPT is a front-end for the GNU Privacy Guard. It just provides
a convinient interface to GPG while GPG does the actual (cryptographic) work.

GnuPG was written by Werner Koch and is Free Software. GnuPG contains all
of the functions WinPT uses for data encrypting, e-signatures and
key management.

WinPT is a Windows utility that sits on the taskbar. In the Windows
Clipboard, you can encrypt, sign, decrypt and verify data. You can also
import and export keys to the Clipboard.

Practically, WinPT is a taskbar front-end for GnuPG. Without GnuPG, WinPT
wouldn't work! Currently not all GnuPG functions are supported. With
all its key edit functions and file operations, WinPT is more than just
an universal e-mail plugin. Together with the filemanager and the keymanager, 
it's like a real graphical GPG user interface.


Install
-------

First you should install the GPG binary, version 1.4.x or later.
(If you want to use a directory other than the default you must modify
the preferences in the WinPT program at Preferences->GPG Preferences).

Next, download the WinPT binary package from the Internet. You can find the
latest WinPT version at http://wald.intevation.org/projects/winpt. 
Create a directory and extract all WinPT files from the archive.


Keyserver Config File
---------------------

Now the keyserver config is read dynamically. That means there is a file
which WinPT reads the keyserver from. The name of this file MUST be
"keyserver.conf". I added a sample config file with the most common
keyservers. Of course it's possible to add own entries. Take a look
at the hints inside the file how to format the entries. If there no file,
the format can be described like this: 'DNS-Name=IP-Address'. Each line
of the file contains such an entry.
But it is recommend that you modify the file directly with the keyserver
dialog in WinPT to keep this file consistent.


Verify the Packet Signature
---------------------------

To verify that the source (or the binary) wasn't changed, you should
verify the package signature with GnuPG. For the process you will need
my OpenPGP public key. If you don't have it, please take a look at
http://www.stud.uni-hannover.de/~twoaday/twoaday.asc or fetch it
via a keyserver (I suggest subkeys.pgp.net).

# gpg --verify winpt-x.x.x-exe.zip.asc
# gpg --verify winpt-x.x.x-src.zip.asc

gpg should output that the signature was correct and that the signature
was created by me.

My key ID is 0xBF3DF9B4: 'Timo Schulz <[email protected]>' or
             0x27F36D14: 'Timo Schulz (Laptop Key) <[email protected]>


Native Language Support (NLS)
-----------------------------

As a new feature WinPT now can handle multiple languages. To activate this
do the following:

- Create a directory where you want to store the locale files
  (the .mo files)

- Rename your favourite .mo file to winpt.mo

- Put all .mo files into this directory
  (For example the gnupg.mo and the winpt.mo)

- Start WinPT and choose the menu entry 'Preferences->GPG Prefs'.
  Set your locale directory to the directory containing winpt.mo.

- Now WinPT runs in the language you have selected.

For an overview what languages are supported take a look at
Po/LINGUAS. It contains all actively maintained languages.

If you are interested in translating WinPT in your native language, please
let me know :-). It's not much work and you do NOT need to be a developer!


Other Documentation
-------------------

For those who are inexperienced with GnuPG it makes sense to download the
GnuPG guide or a HOWTO. There are many sites for this, but you can start
with the GnuPG site. This site is available in many languages. I prefer
the GNU Privacy Handbook. It contains background information that makes
working with GnuPG more effective.

http://www.gnupg.org

General questions (look first at the topic point), can be sent to one of the
mailing lists.

GPG user list [email protected]
GPG developer list [email protected]

At the moment the only available documentation for WinPT is this file. In
future releases I will include HTML documentation.


Mailing Lists
-------------

If you want to get the latest information, reports, or discussions about
WinPT you can subscribe to one of the WinPT mailing lists. There is a list
for users and one for developers. All lists are in English! To subscribe
visit http://wald.intevation.org and go to the WinPT project site.

Please, before you send a message to the list take a look at the FAQ,
the README files and the list archives. It's possible that your question 
is already answered there!


Hotkey for Common Commands
--------------------------

WinPT supports shortcuts, or 'Hotkeys', for the main gpg commands.  These
keys are registered system wide, so you can use them from any window. If you
have some problems with this keys, you can change the hotkeys in the
preferences dialog.

Encrypt Clipboard        CTRL+ALT+e
Sign & Encrypt           CTRL+ALT+b
Decrypt/verify Clipboard CTRL+ALT+d
Sign Clipboard           CTRL+ALT+s
Export Clipboard         CTRL+ALT+x
Import Clipboard         CTRL+ALT+i

In case of an error, it's possible that another program already uses
some of the hotkeys. WinPT will tell you which hotkey wasn't installed properly
so it's easier to figure out which hotkey caused the problem.


Current Window Support
----------------------

WinPT allows you to use the main operations (sign and encrypt)
within the current window. This only works if the current window contains
text. For example, a mailer window with the message, a text editor or a
simple edit field. There are some kind of windows that are NOT
supported.

The easiest way to access this feature is using the hotkeys. Note: if
you use this feature the text will automatically be cut, encrypted
and pasted again in the window. You don't need to do anything manually.

Encrypt current window         ALT+SHIFT+e
Decrypt/verify current window  ALT+SHIFT+d
Sign current window            ALT+SHIFT+s

Alternately you can use the WinPT menu for the current window support.
Please note, that the mode doesn't work very well if you use the menu
entry. I recommend to use it with the hotkeys until I fix this problem.


Word Wrapping
-------------

As a new feature, WinPT can wrap lines at a specific column. You can set
the value for this feature in the preferences dialog. If you don't want
to use this feature, you only need to set the value to "0".


Default keyid for Signing
-------------------------

There are two ways to set the default keyid. The best solution is to
set the "default-key" entry in the GPG options file.
The second solution is that you use the Key Manager to set a default
key. If no default key was found, WinPT uses the first useable key in
the secret key cache.


File Manager
------------

The filemanager is used to perform GPG operations on files. In further releases
I'll add more commands. Currently, encrypt, decrypt, sign and verify
is available. To add a file to the list element, you can use drag & drop
or use the 'Open' menu entry, like Windows Explorer.

Please note that this code is under heavy development, but is should be
fairly stable. It possible that some parts don't work as expected, but
feel free to mail me about any bugs!


Proxy Support
--------------

If you are not able to connect directly to the internet, you can
use the proxy settings. To enable proxy support, you need to start
the keyserver dialog and use the "change" button to set a proxy.
Now the keyserver code uses the proxy instead of the direct connection.

If your proxy needs some kind of authentification, you can use
"proxy_user" and "proxy_pass". Then for each request the data
is used. The code was tested with some HTTP/WWW proxies but it's
also possible that it does *not* work with some proxies! Please tell
me if you've problems with your proxy server.


Debug Mode
----------

To make the detection of bugs and programming mistakes easier, WinPT
contains a built-in debug mode.

It can be activated with the '--enable-debug'
switch on the command line. Then the WinPT output is more verbose and all
steps are logged a in a file with the name "gpgme.dbg". This file is stored
in the current directory and ONLY contains GPG related information. If you
think it is a WinPT problem, you can find a debug file in c:\windows\temp.
The name of this file is "winpt.log". It's possible that this file is very
large, so do NOT forget to compress it.

After an error has occured, it would be very useful to send this file to me.
Which file you'll send depends on the occured error. Don't use the debug
mode for your usual work; it slows down both GPG and WinPT.
1	twoaday	187	WinPT - The Windows Privacy Tray
2	twoaday	326	=================================
3	twoaday	50
4	twoaday	180
5	twoaday	246	Bugs and Improvements
6			---------------------
7	twoaday	50
8	twoaday	187	I have tried to thoroughly test this program, but if you've found a bug,
9	twoaday	180	please send me a message with a full error description or go directly
10			to http://wald.intevation.org and use the WinPT bug tracking system.
11	twoaday	50
12			Please include as much detail as possible including OS version, WinPT
13			version, and GPG version in use. Please summarize your gpg configuration
14			and describe any special programs or configurations on your machine.
15
16			I try to fix bugs as quickly as possible and will upload all updates to
17	twoaday	271	http://wald.intevation.org/projects/winpt
18	twoaday	50
19
20	twoaday	246	Legacy Windows versions
21	twoaday	282	-----------------------
22	twoaday	218
23			I know a lot of people still user old versions of WinPT but it is very
24			hard to test the code on all these platforms and thus I decided to
25			obsolete the support for these OS versions: Win95, WinME/98. The code
26			works on 98/ME without known limitations but if you will encounter
27			a serious problem, I doubt I can fix it without having this OS and
28	twoaday	282	this is the major problem! It is likewise with older NT based systems
29			like NT4 and, with each new year, Win2K.
30	twoaday	218
31
32	twoaday	246	What is WinPT?
33			--------------
34	twoaday	50
35	twoaday	180	WinPT is a front-end for the GNU Privacy Guard. It just provides
36			a convinient interface to GPG while GPG does the actual (cryptographic) work.
37	twoaday	50
38	twoaday	180	GnuPG was written by Werner Koch and is Free Software. GnuPG contains all
39	twoaday	184	of the functions WinPT uses for data encrypting, e-signatures and
40	twoaday	50	key management.
41	twoaday	184
42	twoaday	50	WinPT is a Windows utility that sits on the taskbar. In the Windows
43			Clipboard, you can encrypt, sign, decrypt and verify data. You can also
44			import and export keys to the Clipboard.
45
46			Practically, WinPT is a taskbar front-end for GnuPG. Without GnuPG, WinPT
47	twoaday	184	wouldn't work! Currently not all GnuPG functions are supported. With
48			all its key edit functions and file operations, WinPT is more than just
49			an universal e-mail plugin. Together with the filemanager and the keymanager,
50			it's like a real graphical GPG user interface.
51	twoaday	50
52
53	twoaday	246	Install
54			-------
55	twoaday	50
56	twoaday	184	First you should install the GPG binary, version 1.4.x or later.
57	twoaday	180	(If you want to use a directory other than the default you must modify
58	twoaday	184	the preferences in the WinPT program at Preferences->GPG Preferences).
59	twoaday	50
60			Next, download the WinPT binary package from the Internet. You can find the
61	twoaday	271	latest WinPT version at http://wald.intevation.org/projects/winpt.
62			Create a directory and extract all WinPT files from the archive.
63	twoaday	50
64
65	twoaday	246	Keyserver Config File
66			---------------------
67	twoaday	50
68			Now the keyserver config is read dynamically. That means there is a file
69			which WinPT reads the keyserver from. The name of this file MUST be
70			"keyserver.conf". I added a sample config file with the most common
71			keyservers. Of course it's possible to add own entries. Take a look
72			at the hints inside the file how to format the entries. If there no file,
73			the format can be described like this: 'DNS-Name=IP-Address'. Each line
74			of the file contains such an entry.
75	twoaday	184	But it is recommend that you modify the file directly with the keyserver
76			dialog in WinPT to keep this file consistent.
77	twoaday	50
78
79	twoaday	246	Verify the Packet Signature
80			---------------------------
81	twoaday	50
82			To verify that the source (or the binary) wasn't changed, you should
83			verify the package signature with GnuPG. For the process you will need
84			my OpenPGP public key. If you don't have it, please take a look at
85	twoaday	282	http://www.stud.uni-hannover.de/~twoaday/twoaday.asc or fetch it
86			via a keyserver (I suggest subkeys.pgp.net).
87	twoaday	50
88	twoaday	180	# gpg --verify winpt-x.x.x-exe.zip.asc
89			# gpg --verify winpt-x.x.x-src.zip.asc
90	twoaday	50
91			gpg should output that the signature was correct and that the signature
92			was created by me.
93
94	twoaday	180	My key ID is 0xBF3DF9B4: 'Timo Schulz <[email protected]>' or
95			0x27F36D14: 'Timo Schulz (Laptop Key) <[email protected]>
96	twoaday	50
97
98	twoaday	246	Native Language Support (NLS)
99			-----------------------------
100	twoaday	50
101			As a new feature WinPT now can handle multiple languages. To activate this
102			do the following:
103
104			- Create a directory where you want to store the locale files
105			(the .mo files)
106
107			- Rename your favourite .mo file to winpt.mo
108
109			- Put all .mo files into this directory
110			(For example the gnupg.mo and the winpt.mo)
111
112			- Start WinPT and choose the menu entry 'Preferences->GPG Prefs'.
113			Set your locale directory to the directory containing winpt.mo.
114
115			- Now WinPT runs in the language you have selected.
116
117	twoaday	282	For an overview what languages are supported take a look at
118			Po/LINGUAS. It contains all actively maintained languages.
119	twoaday	50
120			If you are interested in translating WinPT in your native language, please
121			let me know :-). It's not much work and you do NOT need to be a developer!
122
123
124	twoaday	246	Other Documentation
125			-------------------
126	twoaday	50
127			For those who are inexperienced with GnuPG it makes sense to download the
128			GnuPG guide or a HOWTO. There are many sites for this, but you can start
129			with the GnuPG site. This site is available in many languages. I prefer
130			the GNU Privacy Handbook. It contains background information that makes
131			working with GnuPG more effective.
132
133			http://www.gnupg.org
134
135			General questions (look first at the topic point), can be sent to one of the
136	twoaday	282	mailing lists.
137	twoaday	50
138	twoaday	184	GPG user list [email protected]
139			GPG developer list [email protected]
140	twoaday	50
141			At the moment the only available documentation for WinPT is this file. In
142			future releases I will include HTML documentation.
143
144
145	twoaday	246	Mailing Lists
146			-------------
147	twoaday	50
148			If you want to get the latest information, reports, or discussions about
149			WinPT you can subscribe to one of the WinPT mailing lists. There is a list
150	twoaday	180	for users and one for developers. All lists are in English! To subscribe
151			visit http://wald.intevation.org and go to the WinPT project site.
152	twoaday	50
153	twoaday	184	Please, before you send a message to the list take a look at the FAQ,
154			the README files and the list archives. It's possible that your question
155			is already answered there!
156	twoaday	50
157
158	twoaday	246	Hotkey for Common Commands
159			--------------------------
160	twoaday	50
161			WinPT supports shortcuts, or 'Hotkeys', for the main gpg commands. These
162			keys are registered system wide, so you can use them from any window. If you
163			have some problems with this keys, you can change the hotkeys in the
164			preferences dialog.
165
166			Encrypt Clipboard CTRL+ALT+e
167			Sign & Encrypt CTRL+ALT+b
168			Decrypt/verify Clipboard CTRL+ALT+d
169			Sign Clipboard CTRL+ALT+s
170			Export Clipboard CTRL+ALT+x
171			Import Clipboard CTRL+ALT+i
172
173	twoaday	180	In case of an error, it's possible that another program already uses
174	twoaday	50	some of the hotkeys. WinPT will tell you which hotkey wasn't installed properly
175			so it's easier to figure out which hotkey caused the problem.
176
177
178	twoaday	246	Current Window Support
179			----------------------
180	twoaday	50
181			WinPT allows you to use the main operations (sign and encrypt)
182			within the current window. This only works if the current window contains
183			text. For example, a mailer window with the message, a text editor or a
184	twoaday	184	simple edit field. There are some kind of windows that are NOT
185			supported.
186	twoaday	50
187			The easiest way to access this feature is using the hotkeys. Note: if
188			you use this feature the text will automatically be cut, encrypted
189			and pasted again in the window. You don't need to do anything manually.
190
191			Encrypt current window ALT+SHIFT+e
192			Decrypt/verify current window ALT+SHIFT+d
193			Sign current window ALT+SHIFT+s
194
195			Alternately you can use the WinPT menu for the current window support.
196			Please note, that the mode doesn't work very well if you use the menu
197			entry. I recommend to use it with the hotkeys until I fix this problem.
198
199
200	twoaday	246	Word Wrapping
201			-------------
202	twoaday	50
203			As a new feature, WinPT can wrap lines at a specific column. You can set
204			the value for this feature in the preferences dialog. If you don't want
205			to use this feature, you only need to set the value to "0".
206
207
208	twoaday	246	Default keyid for Signing
209			-------------------------
210	twoaday	50
211			There are two ways to set the default keyid. The best solution is to
212	twoaday	180	set the "default-key" entry in the GPG options file.
213	twoaday	184	The second solution is that you use the Key Manager to set a default
214			key. If no default key was found, WinPT uses the first useable key in
215			the secret key cache.
216	twoaday	50
217
218	twoaday	246	File Manager
219	twoaday	50	------------
220
221			The filemanager is used to perform GPG operations on files. In further releases
222			I'll add more commands. Currently, encrypt, decrypt, sign and verify
223			is available. To add a file to the list element, you can use drag & drop
224			or use the 'Open' menu entry, like Windows Explorer.
225
226			Please note that this code is under heavy development, but is should be
227			fairly stable. It possible that some parts don't work as expected, but
228			feel free to mail me about any bugs!
229
230
231	twoaday	246	Proxy Support
232	twoaday	50	--------------
233
234			If you are not able to connect directly to the internet, you can
235	twoaday	184	use the proxy settings. To enable proxy support, you need to start
236			the keyserver dialog and use the "change" button to set a proxy.
237			Now the keyserver code uses the proxy instead of the direct connection.
238	twoaday	50
239			If your proxy needs some kind of authentification, you can use
240			"proxy_user" and "proxy_pass". Then for each request the data
241			is used. The code was tested with some HTTP/WWW proxies but it's
242			also possible that it does not work with some proxies! Please tell
243			me if you've problems with your proxy server.
244
245
246	twoaday	246	Debug Mode
247			----------
248	twoaday	50
249			To make the detection of bugs and programming mistakes easier, WinPT
250			contains a built-in debug mode.
251
252			It can be activated with the '--enable-debug'
253			switch on the command line. Then the WinPT output is more verbose and all
254			steps are logged a in a file with the name "gpgme.dbg". This file is stored
255			in the current directory and ONLY contains GPG related information. If you
256			think it is a WinPT problem, you can find a debug file in c:\windows\temp.
257			The name of this file is "winpt.log". It's possible that this file is very
258			large, so do NOT forget to compress it.
259
260			After an error has occured, it would be very useful to send this file to me.
261			Which file you'll send depends on the occured error. Don't use the debug
262			mode for your usual work; it slows down both GPG and WinPT.