Fix two encoding issues
[gpgol.git] / doc / gpgol.texi
1 \input texinfo
2 @documentencoding ISO-8859-1
3 @setfilename gpgol.info
4 @include version.texi
5 @settitle The GpgOL Technical Manual
6
7 @dircategory GnuPG Plugin
8 @direntry
9 * gpgol: (gpgol).              An Outlook Plugin for GnuPG.
10 @end direntry
11
12 @macro clnt
13   @sc{c:} @c
14 @end macro
15 @macro srvr
16   @sc{s:} @c
17 @end macro
18
19
20
21 @c Unify some of the indices.
22 @syncodeindex tp fn
23 @syncodeindex pg fn
24
25 @copying
26 This is @cite{The GpgOL Technical Manual} for @acronym{GpgOL} (version
27 @value{VERSION}, @value{UPDATED-MONTH}).
28
29 @iftex
30 Published by g10 Code GmbH@*
31 Hüttenstr. 61@*
32 40699 Erkrath, Germany
33 @end iftex
34
35 Copyright @copyright{} 2007, 2008 g10 Code GmbH
36
37 @quotation
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU General Public License as published by the
40 Free Software Foundation; either version 3 of the License, or (at your
41 option) any later version. The text of the license can be found in the
42 section entitled ``Copying''.
43 @end quotation
44 @end copying
45
46 @c
47 @c Titlepage
48 @c
49 @setchapternewpage odd
50 @titlepage
51 @title The GpgOL Technical Manual
52 @subtitle Version @value{VERSION}
53 @subtitle @value{UPDATED-MONTH}
54
55 @sp 3
56
57 @sp 3
58
59 @author Werner Koch (@email{wk@@gnupg.org})
60
61 @page
62 @vskip 0pt plus 1filll
63 @insertcopying
64 @end titlepage
65
66 @ifnothtml
67 @contents
68 @page
69 @end ifnothtml
70
71 @c @ifhtml
72 @c @center @image{logo}
73 @c @end ifhtml
74
75 @ifnottex
76 @node Top
77 @top
78
79 @insertcopying
80
81 @noindent
82 This file documents @acronym{GpgOL}; a GnuPG plugin for Microsoft's
83 Outlook MUA.
84 @end ifnottex
85
86
87 @menu
88 * Introduction::                How to use this manual.
89 * Assuan Protocol::             Description of the UI server protocol.
90 * MAPI Properties::             MAPI Properties used by GpgOL.
91 * Registry Settings::           How GpgOL uses the Registry.
92 * MAPI Providers::              What MAPI Storage or Transport providers
93                                 can do to help GpgOL.
94
95 Appendices
96
97 * Copying::                     The GNU General Public License says how you
98                                 can copy and share this manual.
99
100 Indices
101
102 * Concept Index::               Index of concepts and programs.
103 * Function and Data Index::     Index of functions, variables and data types.
104
105 @end menu
106
107 @ifhtml
108 @page
109 @summarycontents
110 @contents
111 @end ifhtml
112
113 @c
114 @c  I N T R O
115 @c
116 @node Introduction
117 @chapter Introduction
118
119 To debug GpgOL you should set the Registry entry
120 @code{HKCU\Software\Gnu\GpgOL:enableDebug} to the string value @code{1}:
121
122 @cartouche
123 @example
124 [HKEY_CURRENT_USER\Software\GNU\GpgOL]
125 "enableDebug"="1"
126 @end example
127 @end cartouche
128
129 This allows easy setting of a debug file by using the extended options
130 menu and enables a few extra menu items.
131
132
133 @c
134 @c  P R O T O C O L  D E S C R I P T I O N
135 @c
136 @node Assuan Protocol
137 @chapter Description of the UI Server Protocol
138
139 All cryptographic operations are done by a server and the server is
140 responsible for all dialogs.  If a a server is not available,
141 @acronym{GpgOL} does not work.
142
143 This protocol used between @acronym{GpgOL} and the User Interface Server
144 (UI server) is specified in the `GPGME Reference Manual', under the
145 heading `The GnuPG UI Server Protocol'.
146
147
148
149 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
150 @c
151 @c  M A P I  P r o p e r t i e s
152 @c
153 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
154 @node MAPI Properties
155 @chapter MAPI Properties used by GpgOL
156
157 GpgOL uses a some custom MAPI properties in the named properties range.
158 Thus their actual numbers are determined at runtime and only the names
159 should be used.  The GUID assigned to these properties is
160 @code{31805ab8-3e92-11dc-879c-00061b031004}.
161
162 @table @code
163
164 @item GpgOL Msg Class
165 This is a STRING8 property used as a override for PR_MESSAGE_CLASS.
166 GpgOL uses this internally for creating messages.
167
168 @item GpgOL Old Msg Class
169 This is a STRING8 property which saves the original PR_MESSAGE_CLASS
170 before GpgOL changes it.
171
172 @item GpgOL Attach Type
173 This is a property of type LONG and used to further describe the
174 attachments created by GpgOL.  These values are used:
175
176   @table @asis
177   @item ATTACHTYPE_MOSS = 1
178   The attachment contains the original MOSS message.  That is either an
179   S/MIME or a PGP/MIME message in its original RFC-2822 format (but only
180   with the relevant MIME parts of the main header).
181
182   @item ATTACHTYPE_FROMMOSS = 2
183   The attachment has been created from the original MOSS attachment.  It
184   will automagically be recreated as needed.  If the attachment has
185   been created from an encrypted message, it is saved re-encrypted under
186   a non-permanent session key.  This session key is valid as long as the
187   current Outlook porcess exists.
188
189   @item ATTACHTYPE_MOSSTEMPL = 3
190   The attachment has been created in the course of sending a message.
191
192   @item ATTACHTYPE_PGPBODY = 4
193   The attachment contains the original PGP message body of PGP inline
194   encrypted messages.  We need to save this away because it may happen
195   that in the course of displaying the plaintext Outlook overwrites the
196   actual body due to internal syncronization.
197   @end table
198
199 @item GpgOL Sig Status
200 This is a property of type STRING8 and used to cache the result of the
201 last signature verification.  It is used with the actual message and
202 consists of a single character, a space and a human readable string
203 (utf-8 encoded).  The first character is used as a machine processable
204 flag indicating the status.  These values are defined:
205
206   @table @code
207   @item #
208   The message is not of interest to us.  GpgOL may flag any message with
209   this signature status to avoid extra processing for messages already
210   known not to need any processing by GpgOL.
211
212   @item @@
213   The message has been created and signed or encrypted by GpgOL.
214
215   @item ?
216   The signature status has not been checked.  This is for example used
217   if the public key to be used for the verification could not be found.
218
219   @item !
220   The signature verified okay and is deemed to be fully valid.
221
222   @item ~
223   The signature was not fully verified.  This often means that the full
224   result information of the signature verification needs to be
225   considered to decide the actual validity.  Used for example if the
226   signing key has expired
227
228   @item -
229   The signature is bad.  Either this means the message has been tampered
230   with or an intermediate message relay has accidently changed
231   the message (e.g. due to recoding).
232
233   @end table
234
235 @item GpgOL Protect IV
236 This binary property is used to store the initialization vector of an
237 re-encrypted attachment.  The existence of this property indicates that
238 the attachment has been encrypted under the non-permanent session key.
239
240 @item GpgOL Charset
241 This is a property of type STRING8 and used to describe the character
242 set of an attachment or of the body.  If this propery is missing the
243 default of UTF-8 is assumed.
244
245 @item GpgOL Last Decrypted
246 This binary property is used on the message to save a session marker to
247 tell GpgOL whether the message as already been decrypted.  If this
248 property does not exists or the session marker does not macth the one of
249 the current session, GpgOL needs to decrypt it again.
250
251 @item GpgOL MIME Info
252 This property is of type STRING8 and used to store the MIME structure of
253 the orginal message.  The content are lines of colon delimited fields.
254 The specification has not yet been finished.
255
256 @item GpgOL Draft Info
257 This is a property of type STRING8 used to preserve crypto settings in a
258 draft message.  For details see the function
259 @code{mapi_set_gpgol_draft_info}.
260
261 @end table
262
263
264 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
265 @c
266 @c  R e g i s t r y  S  e t t i n g s
267 @c
268 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
269 @node Registry Settings
270 @chapter How GpgOL uses the Registry
271
272 This is a list of registry entries GpgOL knows about.
273
274 @table @code
275
276 @item HKLM\Software\GNU\GnuPG:Install Directory
277 This is used by GnuPG to describe the directory where GnupG has been
278 installed.  GpgOL requires this to get the location of the localedir
279 which is used to show translated strings (@file{gpgol.mo}).  It is
280 further used to check whether GnuPG has been installed at all.
281
282 @item HKCU\Software\GNU\GnuPG:UI Server
283 If the UI server could not be connected, GpgOL tries to start the one
284 given in this entry.  It is assumed that the UI server is stored in the
285 @code{Install Directory} (as described above).  This Registry entry
286 gives the actual command name relative to this directory.  If the key
287 does not exist, is is first searched below @code{HKLM} and then it
288 defaults to @code{kleopatra.exe}.
289
290 @item HKCU\Software\GNU\GpgOL:enableDebug
291 Setting this key to the string @code{1} enables a few extra features in
292 the UI, useful only for debugging.  Setting it to values larger than 1
293 make the log file output more verbose; these are actually bit flags
294 according to the following table (which may change with any release):
295 @table @code
296 @item 2 (0x0002) (ioworker)
297 Tell what the Assuan I/O scheduler is doing.
298 @item 4 (0x0004) (ioworker-extra)
299 Even more verbose Assuan I/O scheduler reporting.
300 @item 8  (0x0008) (filter)
301 Tell what the filter I/O system is doing.
302 @item 16 (0x0010) (filter-extra)
303 Tell how the filter I/O locks the resources.
304 @item 32 (0x0020) (memory)
305 Tell about resource allocation.
306 @item 64 (0x0040) (commands)
307 Tell about command events.
308 @item 128 (0x0080) (mime-parser)
309 Tell what the MIME parser is doing
310 @item 256 (0x0100) (mime-data)
311 Print data lines while parsing MIME.
312 @item 512 (0x0200) (oom)
313 Outlook Object Model reporting.
314 @item 1024 (0x0400) (oom-extra)
315 Verbose OOM allocation and advising reporting.
316 @end table
317 You may use the regular C-syntax for entering the value.  As an
318 alternative you may use the names of the flags, separated by space or
319 comma.
320
321
322 @item HKCU\Software\GNU\GpgOL:logFile
323 If the value is not empty, GpgOL takes this as a log file and appends
324 debug information to this file.  The file may get very large.
325
326 @item HKCU\Software\GNU\GpgOL:compatFlags
327 This is a string consisting of @code{0} and @code{1} to enable certain
328 compatibility flags.  Not generally useful; use the source for a
329 description.
330
331 @item HKCU\Software\GNU\GpgOL:enableSmime
332 @itemx HKCU\Software\GNU\GpgOL:defaultProtocol
333 @itemx HKCU\Software\GNU\GpgOL:encryptDefault
334 @itemx HKCU\Software\GNU\GpgOL:signDefault
335 @itemx HKCU\Software\GNU\GpgOL:previewDecrypt
336 @itemx HKCU\Software\GNU\GpgOL:storePasswdTime
337 @itemx HKCU\Software\GNU\GpgOL:encodingFormat
338 @itemx HKCU\Software\GNU\GpgOL:defaultKey
339 @itemx HKCU\Software\GNU\GpgOL:enableDefaultKey
340 @itemx HKCU\Software\GNU\GpgOL:preferHtml
341 These registry keys store the values from the configuration dialog.
342
343 @item HKCU\Software\GNU\GpgOL:svnRevision
344 Obsolete since 1.1.3.
345
346 @item HKCU\Software\GNU\GpgOL:gitCommit
347 When leaving GpgOL's options dialog, the GIT commit id of the current
348 version will be stored in this entry.  This is used to display a note
349 after software upgrades.
350
351
352 @end table
353
354 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
355 @c
356 @c  MAPI Providers
357 @c
358 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
359 @node MAPI Providers
360 @chapter What MAPI Storage or Transport providers can do to help GpgOL
361
362 GpgOL uses some tricks to make decryption of OpenPGP message better fit
363 into the Outlook framework.  This is due to a lack of proper Plugin API
364 for Outllok and because some features of Outlook --- meant as a security
365 measure --- hinder a better implementation.  That is not to say that
366 Outlook will be less secure when used with GpgOL --- to the opposite:
367 Due to encryption and digital signature reading and sending mail with
368 GpgOL support can be much more secure than using Outlook as is.
369
370 There are some points where custom MAPI storage or transport
371 providers can help GpgOL to gain better performance and to make it more
372 secure.
373
374 @section MAPI Message Class Renaming
375
376 To implement S/MIME processing using its own engine, GpgOL needs to
377 inhibit Outlook from doing the S/MIME before the message is passed to
378 the ECE hooks.  As usual this is done by changing the message class
379 (PR_MESSAGE_CLASS).  For new message this happens right away at the
380 OnDelivery hook; for already existing messages GpgOL tries to detect
381 the case at several other places (which is less reliable but in general
382 works).
383
384 @noindent
385 The renaming is very straightforward:
386
387 @itemize @bullet
388 @item
389 If the message class is just @code{IPM.Note} extra tests are done to
390 figure out a suitable message class.  This yields one of these new
391 message classes:
392
393 @table @code
394 @item IPM.Note.GpgOL.OpaqueSigned
395 @item IPM.Note.GpgOL.OpaqueEncrypted
396 @item IPM.Note.GpgOL.ClearSigned
397 @item IPM.Note.GpgOL.PGPMessage
398 @end table
399
400 @item
401 If the message class is either @code{IPM.Note.SMIME} or that one
402 followed by a dot and a subclass, the @code{SMIME} string is replaced
403 by @code{GpgOL}.
404
405 @item
406 If the message class is @code{IPM.Note.Secure.CexSig} or
407 @code{IPM.Note.Secure.CexEnc} the class is changed depending on other
408 information to one of:
409
410 @table @code
411 @item IPM.Note.GpgOL.OpaqueSigned
412 @item IPM.Note.GpgOL.OpaqueEncrypted
413 @item IPM.Note.GpgOL.MultipartSigned
414 @item IPM.Note.GpgOL
415 @item IPM.Note.GpgOL.ClearSigned
416 @item IPM.Note.GpgOL.PGPMessage
417 @end table
418
419 @end itemize
420
421 To revert these message class changes one need to replace any message
422 class prefix of @code{IPM.Note.GpgOL} by @code{IPM.Note.SMIME}.  There
423 are two caveats however:
424
425 @itemize
426
427 @item
428 GpgOL copies or flags the original MOSS attachment as created by
429 Outlook to a new attachment with the attach type set to ATTACHTYPE_MOSS.
430 If such an attachment exists it should be converted back to the original
431 attachment (or used to convert the message back to RFC-822).  It might
432 however not exist and in this case there should be only one attachment
433 at all as created by Outlook, so no further changes are required.
434
435 @item
436 Inline PGP encrypted mails (@code{IPM.Note.GpgOL.PGPMessage}) might have
437 a wrong PR_BODY. This condition can be detected by the existance of an
438 attachment named @file{gpgolPGP.dat}, flagged as hidden and with the
439 attach type ATTACHTYPE_PGPBODY (See above under MAPI Properties).  If
440 such an attachment exists, it should be copied to PR_BODY and may then
441 be deleted.
442 @end itemize
443
444 @noindent
445 Note that reverting original CryptoEx message classes (@code{CexSig}
446 etc.) back is not possible.  They are identical to GpgOL messages.
447
448
449 @section MAPI Attachment Processing
450
451 GpgOL creates a couple of attachments for the purpose of storing a
452 parsed mail and to allow Outlook to display attachments in the usual way
453 without sending them as plaintext to the storage.  The attachments are
454 only stored on the local disk while being opened from the attachment's
455 context menu for viewing.  Almost all these attachments are ephemeral and
456 may be deleted when not displayed.  GpgOL re-creates them by parsing the
457 original message if neeeded.  In fact they are always re-created after
458 Outlook as been started again.  This is because the attachments holding
459 the plaintext are symmetrical encrypted with an ephemeral session key,
460 only valid as long as Outlook runs.
461
462 FIXME:  Needs more documentation.
463
464
465 @section MAPI PR_BODY Processing
466
467 GpgOL does not use the PR_BODY property.  This is because internal
468 Outlook syncronisation may change that property after the plaintext of a
469 message has been displayed.  In general this is not a problem because
470 the messages processed by GpgOL do not use that property (the orginal
471 S/MIME and PGP/MIME message is stored in attachments).  However, there
472 is one exception: Inline PGP message (in contrast to the modern PGP/MIME
473 messages) are conveyed in the PR_BODY.  To avoid changing that orginal
474 mail, GpgOL copies such a body to a new attachment named
475 @file{gpgolPGP.dat}, flags it as hidden and sets the attach type to
476 ATTACHTYPE_PGPBODY (See above under MAPI Properties).  That attachment
477 may never be deleted!
478
479 Due to internal OL syncronisation, plaintext data may end up in PR_BODY,
480 GpgOL tries hard to delete PR_BODY so that it nevers shows up in the
481 MAPI storage.  However this is hard and here a storage provider can help
482 by deleting PR_BODY under one of these conditions:
483
484 @itemize @bullet
485
486 @item
487 If the message class is either @code{IPM.Note.GpgOL.MultipartEncrypted}
488 or @code{IPM.Note.GpgOL.OpaqueEncrypted} and in addition the message has
489 a property @code{GpgOL Last Decrypted} (with any value), delete the
490 properties @code{PR_BODY} and @code{PR_BODY_HTML}.
491
492 @item
493 If the message class is @code{IPM.Note.GpgOL.PGPMessage} and an
494 attachment of ATTACHTYPE_PGPBODY with a filename @file{gpgolPGP.dat}
495 exists, delete the properties @code{PR_BODY} and @code{PR_BODY_HTML}.
496
497 @end itemize
498
499 Instead of deleting it should be sufficient to make sure
500 that such PR_BODYs are not updated and don't make it to the disk or a
501 strage server.
502
503 Implementing such a feature would really help with end-to-end encryption
504 where the security policy requires that the plaintext of an encrypted
505 message will never be stored on a disk or leave the local machine.
506
507
508 @section Filtering GpgOL internal properties
509
510 To avoid attacks by importing TNEF data with certain GpgOL internal
511 properties, a MAPI provider may want to filter them out when receiving a
512 message from an external location.  It is not yet clear whether this is
513 really needed.
514
515 FIXME.
516
517
518
519
520
521 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
522 @c
523 @c   A P P E N D I X
524 @c
525 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
526
527 @include gpl.texi
528
529 @c
530 @c  I N D E X E S
531 @c
532 @node Concept Index
533 @unnumbered Concept Index
534 @printindex cp
535 @node Function and Data Index
536 @unnumbered Function and Data Index
537 @printindex fn
538
539 @bye
540
541 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
542 @c
543 @c E D I T O R ' S   A T T I C
544 @c
545 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
546
547 What about the message class mangling?
548
549 * On receiving a new message GpgOL checks the MAPI message class
550   property of the message and if this is an S/MIME message class
551   ("IPM.Note.SMIME"), it is changed to a GpgOL specific one
552   ("IPM.Note.GpgOL").  This change is required so that OL does not not
553   apply its own S/MIME handler to the message but leaves it unchanged in
554   the message store.
555
556 * For ease of implementation the same thing applies to PGP messgaes,
557   although OL would not touch these messages.
558
559 * When reading a message GpgOL quickly checks the message class and if
560   it is "IPM.Note.GpgOL" it will hook itself into the code path and
561   decrypt/verify the message.
562
563 * Messages already in the message store before GpgOL was installed are
564   handled differently: Here an Outlook specific event is used to change
565   the message class when browsing the messages folder.  This code path
566   is not fully ready as it requires the installation of an ECF(ile)
567   which has to be done manually as of now.
568
569 * If GpgOL is deinstalled, the existing S/MIME messages can't be
570   decrypted or verified by Outlook's internal S/MIME support.
571   Multipart/signed messages are still readable, though.  We plan to add
572   a little tool for changing the GpgOL message classes back to
573   "IPM.Note.SMIME" which in turn allows using internal S/MIME support
574   again.
575
576
577
578 @c Local Variables:
579 @c coding: latin-1
580 @c End: