Annotation of /trunk/README

                        The Windows Privacy Tray


Index
     1. Notice
     2. Bugs and improvements
     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. Notice
---------

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 debug 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


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 and 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
doesn't work! Currently not all GnuPG functions are supported. Because of
all the new features, WinPT is more then just an universal e-mail plugin.
Together with the filemanager and the keymanager, it's like a real GUI.


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

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 releated files.


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.


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

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 (English) [email protected]
GPG Developer list (English) [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
or the README files. 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
yet!

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 to let WinPT figure out it from the secret key cache,
the first key in this cache is the default keyid. Warning, with this method
it's possible that another keyid is chosen (because of the order in 
which the keyring was read!).


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.2 UserID
-------------

Gives you an overview about all user id's from a public key. The validity
of each is also listed.


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