Contents of /trunk/README

                        WinPT - The Windows Privacy Tray


Index
     1. Note
     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. 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


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