Annotation of /trunk/README

                        WinPT - The Windows Privacy Tray


Note
-----

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


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


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!


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


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


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.


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