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