Annotation of /trunk/README

                        WinPT - The Windows Privacy Tray


Index
     1. Note
     2. Bugs and improvements
     2.1 Legacy Windows versions
     3. What is WinPT?
     4. Install
      4.1 Keyserver config file
     5. Verify the packet signature
     6. Native language support
     7. Other documentation
     8. Mailing lists
     9. Hotkeys for common commands
    10. Current window support
    11. Word wrapping
    12. Default key for signing
    13. Commands
     13.1 File manager
     13.2 Key manager
      13.2.1 Edit
      13.2.2 UserID
      13.2.3 Delete
      13.2.4 Sign
      13.2.5 Revoke cert
      13.2.6 Check sigs
    13.3 Keyserver
     13.3.1 Keyserver searching
     13.3.2 Proxy support
    14. Debug mode
    16. Features of the dialogs
    16. Features of the dialogs


1. Note
---------

This is only a quick guide for WinPT. For the moment the program is its own
documentation. This is subject to change.


2. 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://www.winpt.org


2.1 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!


3. 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.


4. 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://www.winpt.org. Create a directory and 
extract all WinPT files from the archive.


4.1 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.


5. 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.winpt.org/twoaday.asc

# 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]>


6. Native language support
--------------------------

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 the moment, WinPT supports these languages:

    * German winpt-de.mo
    * Japanese winpt-jp.mo

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!


7. 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. All GnuPG lists are in English.

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.


8. 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!


9. 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.


10. 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.


11. 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".


12. 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.


13. Commands
------------


13.1 Filemanager
----------------

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!


13.2 Keymanager
---------------

13.2.1 Edit
-----------

Here you access some of the "edit-key" command from the GPG command
line.


13.2.3 Delete
-------------

With it you can delete public keys and/or key pairs.


13.2.4 Sign
-----------

This is an interface to sign a public key.


13.2.5 Revoke cert
------------------

Generate a revocation certificate for the chosen key.


13.2.7 Check sigs
-----------------

With this command you can check the signatures from a special public key.


13.2.7 Key properties
---------------------

This dialog is an easy way to get an overview about the given key.
To activate this dialog, you've to double click on a key item in the
key management dialog. Then a dialog with all related information about
the selected key will open.


13.3 Keyserver
--------------

13.3.1 Keyserver searching
--------------------------

This new feature works exactly like the normal keyserver support.
You have to enter the pattern, then chose a keyserver. The command
is started with the "Search" button. The next dialog contains all
found keys from the keyserver. If you want, you can import a key
from this list by select the key and press the "Receive" button.

13.3.2 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.


14. 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.


16. Features of the dialogs
----------------------------

This sections contains hints about the special features of some dialogs.
Currently this is only valid for dialog with listview controls.

o Selection of an entry for the GPG main commands

If you only want to select one recipient, you can also double click
the line which the recipient you want to choose. Then the command
is automatically invoked and you don't need to click the "OK" button.

o Context menu for the key manager

Now the keymanager supports a context menu. To activate it, you should
click with the right mouse button on a selected item.

o Generic keys known from the Explorer

For example the key manager supports generic keys like:
DELETE = secure the selected key.

o Context menu for the file manager

This popup menu is similar to the key manager menu.

1	twoaday	187	WinPT - The Windows Privacy Tray
2	twoaday	50
3	twoaday	180
4	twoaday	50	Index
5	twoaday	187	1. Note
6	twoaday	50	2. Bugs and improvements
7	twoaday	218	2.1 Legacy Windows versions
8	twoaday	50	3. What is WinPT?
9			4. Install
10			4.1 Keyserver config file
11			5. Verify the packet signature
12			6. Native language support
13			7. Other documentation
14			8. Mailing lists
15			9. Hotkeys for common commands
16			10. Current window support
17			11. Word wrapping
18			12. Default key for signing
19			13. Commands
20			13.1 File manager
21			13.2 Key manager
22			13.2.1 Edit
23			13.2.2 UserID
24			13.2.3 Delete
25			13.2.4 Sign
26			13.2.5 Revoke cert
27			13.2.6 Check sigs
28			13.3 Keyserver
29			13.3.1 Keyserver searching
30			13.3.2 Proxy support
31			14. Debug mode
32			16. Features of the dialogs
33			16. Features of the dialogs
34
35
36	twoaday	187	1. Note
37	twoaday	50	---------
38
39			This is only a quick guide for WinPT. For the moment the program is its own
40	twoaday	180	documentation. This is subject to change.
41	twoaday	50
42
43			2. Bugs and improvements
44			------------------------
45
46	twoaday	187	I have tried to thoroughly test this program, but if you've found a bug,
47	twoaday	180	please send me a message with a full error description or go directly
48			to http://wald.intevation.org and use the WinPT bug tracking system.
49	twoaday	50
50			Please include as much detail as possible including OS version, WinPT
51			version, and GPG version in use. Please summarize your gpg configuration
52			and describe any special programs or configurations on your machine.
53
54			I try to fix bugs as quickly as possible and will upload all updates to
55			http://www.winpt.org
56
57
58	twoaday	218	2.1 Legacy Windows versions
59
60			I know a lot of people still user old versions of WinPT but it is very
61			hard to test the code on all these platforms and thus I decided to
62			obsolete the support for these OS versions: Win95, WinME/98. The code
63			works on 98/ME without known limitations but if you will encounter
64			a serious problem, I doubt I can fix it without having this OS and
65			this is the major problem!
66
67
68	twoaday	50	3. What is WinPT?
69			-----------------
70
71	twoaday	180	WinPT is a front-end for the GNU Privacy Guard. It just provides
72			a convinient interface to GPG while GPG does the actual (cryptographic) work.
73	twoaday	50
74	twoaday	180	GnuPG was written by Werner Koch and is Free Software. GnuPG contains all
75	twoaday	184	of the functions WinPT uses for data encrypting, e-signatures and
76	twoaday	50	key management.
77	twoaday	184
78	twoaday	50	WinPT is a Windows utility that sits on the taskbar. In the Windows
79			Clipboard, you can encrypt, sign, decrypt and verify data. You can also
80			import and export keys to the Clipboard.
81
82			Practically, WinPT is a taskbar front-end for GnuPG. Without GnuPG, WinPT
83	twoaday	184	wouldn't work! Currently not all GnuPG functions are supported. With
84			all its key edit functions and file operations, WinPT is more than just
85			an universal e-mail plugin. Together with the filemanager and the keymanager,
86			it's like a real graphical GPG user interface.
87	twoaday	50
88
89			4. Install
90			----------
91
92	twoaday	184	First you should install the GPG binary, version 1.4.x or later.
93	twoaday	180	(If you want to use a directory other than the default you must modify
94	twoaday	184	the preferences in the WinPT program at Preferences->GPG Preferences).
95	twoaday	50
96			Next, download the WinPT binary package from the Internet. You can find the
97	twoaday	180	latest WinPT version at http://www.winpt.org. Create a directory and
98	twoaday	184	extract all WinPT files from the archive.
99	twoaday	50
100
101			4.1 Keyserver config file
102			-------------------------
103
104			Now the keyserver config is read dynamically. That means there is a file
105			which WinPT reads the keyserver from. The name of this file MUST be
106			"keyserver.conf". I added a sample config file with the most common
107			keyservers. Of course it's possible to add own entries. Take a look
108			at the hints inside the file how to format the entries. If there no file,
109			the format can be described like this: 'DNS-Name=IP-Address'. Each line
110			of the file contains such an entry.
111	twoaday	184	But it is recommend that you modify the file directly with the keyserver
112			dialog in WinPT to keep this file consistent.
113	twoaday	50
114
115			5. Verify the packet signature
116			------------------------------
117
118			To verify that the source (or the binary) wasn't changed, you should
119			verify the package signature with GnuPG. For the process you will need
120			my OpenPGP public key. If you don't have it, please take a look at
121			http://www.winpt.org/twoaday.asc
122
123	twoaday	180	# gpg --verify winpt-x.x.x-exe.zip.asc
124			# gpg --verify winpt-x.x.x-src.zip.asc
125	twoaday	50
126			gpg should output that the signature was correct and that the signature
127			was created by me.
128
129	twoaday	180	My key ID is 0xBF3DF9B4: 'Timo Schulz <[email protected]>' or
130			0x27F36D14: 'Timo Schulz (Laptop Key) <[email protected]>
131	twoaday	50
132
133			6. Native language support
134			--------------------------
135
136			As a new feature WinPT now can handle multiple languages. To activate this
137			do the following:
138
139			- Create a directory where you want to store the locale files
140			(the .mo files)
141
142			- Rename your favourite .mo file to winpt.mo
143
144			- Put all .mo files into this directory
145			(For example the gnupg.mo and the winpt.mo)
146
147			- Start WinPT and choose the menu entry 'Preferences->GPG Prefs'.
148			Set your locale directory to the directory containing winpt.mo.
149
150			- Now WinPT runs in the language you have selected.
151
152			For the moment, WinPT supports these languages:
153
154			* German winpt-de.mo
155	twoaday	184	* Japanese winpt-jp.mo
156	twoaday	50
157			If you are interested in translating WinPT in your native language, please
158			let me know :-). It's not much work and you do NOT need to be a developer!
159
160
161			7. Other documentation
162			----------------------
163
164			For those who are inexperienced with GnuPG it makes sense to download the
165			GnuPG guide or a HOWTO. There are many sites for this, but you can start
166			with the GnuPG site. This site is available in many languages. I prefer
167			the GNU Privacy Handbook. It contains background information that makes
168			working with GnuPG more effective.
169
170			http://www.gnupg.org
171
172			General questions (look first at the topic point), can be sent to one of the
173			mailing lists. All GnuPG lists are in English.
174
175	twoaday	184	GPG user list [email protected]
176			GPG developer list [email protected]
177	twoaday	50
178			At the moment the only available documentation for WinPT is this file. In
179			future releases I will include HTML documentation.
180
181
182			8. Mailing lists
183			----------------
184
185			If you want to get the latest information, reports, or discussions about
186			WinPT you can subscribe to one of the WinPT mailing lists. There is a list
187	twoaday	180	for users and one for developers. All lists are in English! To subscribe
188			visit http://wald.intevation.org and go to the WinPT project site.
189	twoaday	50
190	twoaday	184	Please, before you send a message to the list take a look at the FAQ,
191			the README files and the list archives. It's possible that your question
192			is already answered there!
193	twoaday	50
194
195			9. Hotkey for common commands
196			-----------------------------
197
198			WinPT supports shortcuts, or 'Hotkeys', for the main gpg commands. These
199			keys are registered system wide, so you can use them from any window. If you
200			have some problems with this keys, you can change the hotkeys in the
201			preferences dialog.
202
203			Encrypt Clipboard CTRL+ALT+e
204			Sign & Encrypt CTRL+ALT+b
205			Decrypt/verify Clipboard CTRL+ALT+d
206			Sign Clipboard CTRL+ALT+s
207			Export Clipboard CTRL+ALT+x
208			Import Clipboard CTRL+ALT+i
209
210	twoaday	180	In case of an error, it's possible that another program already uses
211	twoaday	50	some of the hotkeys. WinPT will tell you which hotkey wasn't installed properly
212			so it's easier to figure out which hotkey caused the problem.
213
214
215			10. Current window support
216			--------------------------
217
218			WinPT allows you to use the main operations (sign and encrypt)
219			within the current window. This only works if the current window contains
220			text. For example, a mailer window with the message, a text editor or a
221	twoaday	184	simple edit field. There are some kind of windows that are NOT
222			supported.
223	twoaday	50
224			The easiest way to access this feature is using the hotkeys. Note: if
225			you use this feature the text will automatically be cut, encrypted
226			and pasted again in the window. You don't need to do anything manually.
227
228			Encrypt current window ALT+SHIFT+e
229			Decrypt/verify current window ALT+SHIFT+d
230			Sign current window ALT+SHIFT+s
231
232			Alternately you can use the WinPT menu for the current window support.
233			Please note, that the mode doesn't work very well if you use the menu
234			entry. I recommend to use it with the hotkeys until I fix this problem.
235
236
237			11. Word wrapping
238			-----------------
239
240			As a new feature, WinPT can wrap lines at a specific column. You can set
241			the value for this feature in the preferences dialog. If you don't want
242			to use this feature, you only need to set the value to "0".
243
244
245	twoaday	180	12. Default keyid for signing
246	twoaday	50	----------------------------
247
248			There are two ways to set the default keyid. The best solution is to
249	twoaday	180	set the "default-key" entry in the GPG options file.
250	twoaday	184	The second solution is that you use the Key Manager to set a default
251			key. If no default key was found, WinPT uses the first useable key in
252			the secret key cache.
253	twoaday	50
254
255			13. Commands
256			------------
257
258
259			13.1 Filemanager
260			----------------
261
262			The filemanager is used to perform GPG operations on files. In further releases
263			I'll add more commands. Currently, encrypt, decrypt, sign and verify
264			is available. To add a file to the list element, you can use drag & drop
265			or use the 'Open' menu entry, like Windows Explorer.
266
267			Please note that this code is under heavy development, but is should be
268			fairly stable. It possible that some parts don't work as expected, but
269			feel free to mail me about any bugs!
270
271
272			13.2 Keymanager
273			---------------
274
275			13.2.1 Edit
276			-----------
277
278			Here you access some of the "edit-key" command from the GPG command
279			line.
280
281
282			13.2.3 Delete
283			-------------
284
285			With it you can delete public keys and/or key pairs.
286
287
288			13.2.4 Sign
289			-----------
290
291			This is an interface to sign a public key.
292
293
294			13.2.5 Revoke cert
295			------------------
296
297			Generate a revocation certificate for the chosen key.
298
299
300			13.2.7 Check sigs
301			-----------------
302
303			With this command you can check the signatures from a special public key.
304
305
306			13.2.7 Key properties
307			---------------------
308
309			This dialog is an easy way to get an overview about the given key.
310			To activate this dialog, you've to double click on a key item in the
311			key management dialog. Then a dialog with all related information about
312			the selected key will open.
313
314
315			13.3 Keyserver
316			--------------
317
318			13.3.1 Keyserver searching
319			--------------------------
320
321			This new feature works exactly like the normal keyserver support.
322			You have to enter the pattern, then chose a keyserver. The command
323			is started with the "Search" button. The next dialog contains all
324			found keys from the keyserver. If you want, you can import a key
325			from this list by select the key and press the "Receive" button.
326
327			13.3.2 Proxy support
328			--------------------
329
330			If you are not able to connect directly to the internet, you can
331	twoaday	184	use the proxy settings. To enable proxy support, you need to start
332			the keyserver dialog and use the "change" button to set a proxy.
333			Now the keyserver code uses the proxy instead of the direct connection.
334	twoaday	50
335			If your proxy needs some kind of authentification, you can use
336			"proxy_user" and "proxy_pass". Then for each request the data
337			is used. The code was tested with some HTTP/WWW proxies but it's
338			also possible that it does not work with some proxies! Please tell
339			me if you've problems with your proxy server.
340
341
342			14. Debug mode
343			--------------
344
345			To make the detection of bugs and programming mistakes easier, WinPT
346			contains a built-in debug mode.
347
348			It can be activated with the '--enable-debug'
349			switch on the command line. Then the WinPT output is more verbose and all
350			steps are logged a in a file with the name "gpgme.dbg". This file is stored
351			in the current directory and ONLY contains GPG related information. If you
352			think it is a WinPT problem, you can find a debug file in c:\windows\temp.
353			The name of this file is "winpt.log". It's possible that this file is very
354			large, so do NOT forget to compress it.
355
356			After an error has occured, it would be very useful to send this file to me.
357			Which file you'll send depends on the occured error. Don't use the debug
358			mode for your usual work; it slows down both GPG and WinPT.
359
360
361			16. Features of the dialogs
362			----------------------------
363
364			This sections contains hints about the special features of some dialogs.
365			Currently this is only valid for dialog with listview controls.
366
367			o Selection of an entry for the GPG main commands
368
369			If you only want to select one recipient, you can also double click
370			the line which the recipient you want to choose. Then the command
371			is automatically invoked and you don't need to click the "OK" button.
372
373			o Context menu for the key manager
374
375			Now the keymanager supports a context menu. To activate it, you should
376			click with the right mouse button on a selected item.
377
378			o Generic keys known from the Explorer
379
380			For example the key manager supports generic keys like:
381			DELETE = secure the selected key.
382
383			o Context menu for the file manager
384
385			This popup menu is similar to the key manager menu.
386