Code cleanups.
[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 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
93 Appendices
94
95 * Copying::                     The GNU General Public License says how you
96                                 can copy and share this manual.
97
98 Indices
99
100 * Concept Index::               Index of concepts and programs.
101 * Function and Data Index::     Index of functions, variables and data types.
102
103 @end menu
104
105 @ifhtml
106 @page
107 @summarycontents
108 @contents
109 @end ifhtml
110
111 @c
112 @c  I N T R O
113 @c
114 @node Introduction
115 @chapter Introduction
116 Bla bla
117
118
119 @c
120 @c  P R O T O C O L  D E S C R I P T I O N
121 @c
122 @node Assuan Protocol
123 @chapter Description of the UI Server Protocol
124
125 This section describes the protocol used between @acronym{GpgOL} and the
126 User Interface Server (UI server).  All cryptographic operations are
127 done by this server and the server is responsible for all dialogs.  If a
128 a server is not available, @acronym{GpgOL} can only use a very limited
129 internal crypto server.
130
131 We assume that the connection has already been established; see the
132 Assuan manual for details.
133
134 @menu
135 * ENCRYPT::                  Encrypt a message.
136 * SIGN::                     Sign a message.
137 * DECRYPT::                  Decrypt a message.
138 * VERIFY::                   Verify a message.
139 * Miscellaneous Commands::   Commands not related to a specific operation.
140 @end menu
141
142
143
144 @node ENCRYPT
145 @section Encrypt a Message
146
147 Before encryption can be done the recipients must be set using the
148 command:
149
150 @deffn Command RECIPIENT @var{string}
151
152 Set the recipient for the encryption.  @var{string} is an RFC-2822
153 recipient name.  This command may or may not check the recipient for
154 validity right away; if it does not all recipients are expected to be
155 checked at the time of the @code{ENCRYPT} command.  All @code{RECIPIENT}
156 commands are cumulative until a successful @code{ENCRYPT} command or
157 until a @code{RESET} command.  Linefeeds are obviously not allowed in
158 @var{string} and should be folded into spaces (which are equivalent).
159 @end deffn
160
161 @noindent
162 To tell the server the source and destination of the data, the next two
163 commands are to be used:
164
165 @deffn Command INPUT FD=@var{n}
166 Set the file descriptor for the message to be encrypted to @var{n}.  The
167 message send to the server is binary encoded. 
168
169 GpgOL is a Windows only program, thus @var{n} is not a libc file
170 descriptor but a regular system handle.  Given that the Assuan
171 connection works over a socket, it is not possible to use regular
172 inheritance to make the file descriptor available to the server.
173 Thus @code{DuplicateHandle} needs to be used to duplicate a handle
174 to the server process.  This is the reason that the server needs to
175 implement the @code{GETINFO pid} command.  Sending this command a second
176 time replaces the file descriptor set by the last one.
177 @c If @var{n} is not given, this commands uses the
178 @c %last file descriptor passed to the application.
179 @c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
180 @c %Libassuan manual}, on how to do descriptor passing.
181 @end deffn
182
183 @deffn Command OUTPUT FD=@var{n}
184 Set the file descriptor to be used for the output (i.e. the encrypted
185 message) to @var{n}.  For OpenPGP, the output needs to be ASCII armored;
186 for CMS, the output needs to be Base-64 encoded.  For details on the
187 file descriptor, see the @code{INPUT} command.
188 @end deffn
189
190 @noindent  
191 The setting of the recipients, the data source and destination may
192 happen in any order, even intermixed.  If this has been done the actual
193 encryption operation is called using:
194
195 @deffn Command ENCRYPT -@w{}-protocol=@var{name}
196
197 This command reads the plaintext from the file descriptor set by the
198 @code{INPUT} command, encrypts it and writes the ciphertext to the file
199 descriptor set by the @code{OUTPUT} command.  The server may (and
200 should) overlap reading and writing.  The recipients used for the
201 encryption are all the recipients set so far.  If any recipient is not
202 usable the server should take appropriate measures to notify the user
203 about the problem and may cancel the operation by returning an error
204 code.  The used file descriptors are a void after this command; the
205 recipient list is only cleared if the server returns success.
206
207 @noindent
208 Because GpgOL uses a streaming mode of operation the server is not
209 allowed to auto select the protocol and must obey to the mandatory
210 @var{protocol} parameter:
211
212 @table @code
213 @item OpenPGP
214 Use the OpenPGP protocol (RFC-2440).
215 @item CMS
216 Use the CMS (PKCS#7) protocol (RFC-3852).
217 @end table
218
219 @end deffn
220
221 To support automagically selection of the protocol depending on the
222 selected keys, the server may implement the follwoing extra command:
223
224 @deffn Command PREP_ENCRYPT [-@w{}-protocol=@var{name}]
225
226 This commands considers all recipients set so far and decides whether it
227 is able to take input and start the actual decryption.  This is kind of
228 a dry-run @command{ENCRYPT} without requiring or using the input and
229 output file descriptors.  The server shall cache the result of any user
230 selection to avoid asking this again when the actual @command{ENCRYPT}
231 command is send.  The @option{--protocol} option is optional; if it is
232 not given, the server should allow the user to select the protocol to be
233 used based on the recipients given or by any other means.
234
235 If this command is given again before a successful @command{ENCRYPT}
236 command, the second one takes effect. 
237
238 Before sending the OK response the server shall tell the client the
239 protocol to be used (either the one given by the argument or the one
240 selected by the user) by means of a status line:
241 @end deffn
242
243 @deffn {Status line} PROTOCOL @var{name}
244 Advise the client to use the protocol @var{name} for the
245 @command{ENCRYPT} command.  The valid protocol names are listed under
246 the description of the @command{ENCRYPT} command.  The server shall emit
247 exactly one PROTOCOL status line.
248 @end deffn
249
250 @noindent
251 Here is an example of a complete encryption sequence; client lines are
252 indicated by a @sc{c:}, server responses by @sc{c:}:
253
254 @smallexample
255 @group
256   @clnt RESET
257   @srvr OK
258   @clnt RECIPIENT foo@@example.net
259   @srvr OK
260   @clnt RECIPIENT bar@@example.com
261   @srvr OK
262   @clnt PREP_ENCRYPT
263   @srvr S PROTOCOL OpenPGP
264   @srvr OK
265   @clnt INPUT FD=17
266   @srvr OK
267   @clnt OUTPUT FD=18
268   @srvr OK
269   @clnt ENCRYPT
270   @srvr OK
271 @end group
272 @end smallexample
273
274
275
276 @node SIGN
277 @section Sign a Message
278
279 The server needs to implement opaque signing as well as detached
280 signing.  Due to the nature of OpenPGP message it is always required to
281 send the entire message to the server; sending just the hash is not
282 possible.  The following two commands are required to set the input and
283 output file descriptors:
284
285 @deffn Command INPUT FD=@var{n}
286 Set the file descriptor for the message to be signed to @var{n}.  The
287 message send to the server is binary encoded.  For details on the file
288 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
289 section.
290 @end deffn
291
292 @deffn Command OUTPUT FD=@var{n}
293 Set the file descriptor to be used for the output.  The output is either
294 the complete signed message or in case of a detached signature just that
295 detached signature.  For OpenPGP, the output needs to be ASCII armored;
296 for CMS, the output needs to be Base-64 encoded.  For details on the
297 file descriptor, see the @code{INPUT} command.
298 @end deffn
299
300 @noindent
301 To allow the server the selection of a non-default signing key the
302 client may optionally use the command:
303
304 @deffn Command SENDER @var{email}
305 @var{email} is the plain ASCII encoded address ("addr-spec" as per
306 RFC-2822) enclosed in angle brackets.  The address set with this command
307 is valid until a successful @code{SIGN} command or until a @code{RESET}
308 command.  A second command overrides the effect of the first one; if
309 @var{email} is not given the server shall use the default signing key.
310 @end deffn
311
312 @noindent
313 The signing operation is then initiated by:
314
315 @deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] 
316 Sign the data set with the @code{INPUT} command and write it to the sink
317 set by OUTPUT.  @var{name} is the signing protocol used for the
318 message. For a description of the allowed protocols see the
319 @code{ENCRYPT} command.  With option @code{--detached} given, a detached
320 signature is created; this is actually the usual way the command is
321 used.
322 @end deffn
323
324 @noindent
325 The client expects the server to send at least this status information
326 before the final OK response:
327
328 @deffn {Status line} MICALG @var{string}
329 The @var{string} represents the hash algorithm used to create the
330 signature. It is used with MOSS style signature messaged and defined by
331 PGP/MIME (RFC-3156) and S/MIME (RFC-3851).  The GPGME library has a
332 supporting function @code{gpgme_hash_algo_name} to return the algorithm
333 name as a string.  This string needs to be lowercased and for OpenPGP
334 prefixed with "@code{pgp-}".
335 @end deffn
336
337
338
339 @node DECRYPT
340 @section Decrypt a Message
341
342 Decryption may include the verification of OpenPGP messages.  This is
343 due to the often used combined signing/encryption modus of OpenPGP.  The
344 client may pass an option to the server to inhibit the signature
345 verification.  The following two commands are required to set the input
346 and output file descriptors:
347
348 @deffn Command INPUT FD=@var{n}
349 Set the file descriptor for the message to be decrypted to @var{n}.  The
350 message send to the server is either binary encoded or --- in the case
351 of OpenPGP --- ASCII armored.  For details on the file descriptor, see
352 the description of @code{INPUT} in the @code{ENCRYPT} section.
353 @end deffn
354
355 @deffn Command OUTPUT FD=@var{n}
356 Set the file descriptor to be used for the output. The output is binary
357 encoded. For details on the file descriptor, see the description of
358 @code{INPUT} in the @code{ENCRYPT} section.
359 @end deffn
360
361 @noindent
362 The decryption is started with the command:
363
364 @deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
365 @var{name} is the encryption protocol used for the message. For a
366 description of the allowed protocols see the @code{ENCRYPT} command.
367 This argument is mandatory.  If the option @option{--no-verify} is given,
368 the server should not try to verify a signature, in case the input data
369 is an OpenPGP combined message.
370 @end deffn
371
372
373 @node VERIFY
374 @section Verify a Message
375
376 The server needs to support the verification of opaque signatures as
377 well as detached signatures.  The kind of input sources controls what
378 kind message is to be verified.
379
380 @deffn Command MESSAGE FD=@var{n}
381 This command is used with detached signatures to set the file descriptor
382 for the signed data to @var{n}. The data is binary encoded (used
383 verbatim).  For details on the file descriptor, see the description of
384 @code{INPUT} in the @code{ENCRYPT} section.
385 @end deffn
386
387 @deffn Command INPUT FD=@var{n}
388 Set the file descriptor for the opaque message or the signature part of
389 a detached signature to @var{n}.  The message send to the server is
390 either binary encoded or -- in the case of OpenPGP -- ASCII armored.
391 For details on the file descriptor, see the description of @code{INPUT}
392 in the @code{ENCRYPT} section.
393 @end deffn
394
395 @deffn Command OUTPUT FD=@var{n}
396 Set the file descriptor to be used for the output. The output is binary
397 encoded and only used for opaque signatures.  For details on the file
398 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
399 section.
400 @end deffn
401
402 @noindent
403 The verification is then started using:
404
405 @deffn Command VERIFY -@w{}-protocol=@var{name}
406 @var{name} is the signing protocol used for the message. For a
407 description of the allowed protocols see the @code{ENCRYPT} command.
408 This argument is mandatory.  Depending on the combination of
409 @code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
410 to select the appropriate verification mode:
411
412 @table @asis
413 @item MESSAGE and INPUT
414 This indicates a detached signature.  Output data is not applicable.
415 @item INPUT 
416 This indicates an opaque signature.  As no output command has been given,
417 the server is only required to check the signature.
418 @item INPUT and OUTPUT
419 This indicates an opaque signature.  The server shall write the signed
420 data to the file descriptor set by the output command.  This data shall
421 even be written if the signatures can't be verified.
422 @end table
423 @end deffn
424
425 @noindent
426 The client expects the server to send at least this status information
427 before the final OK response:
428
429 @deffn {Status line} SIGSTATUS @var{flag} @var{displaystring}
430 Returns the status for the signature and a short string explaining the
431 status.  Valid values for @var{flag} are:
432
433 @table @code
434 @item none
435 The message has a signature but it could not not be verified due to a
436 missing key.
437 @item green
438 The signature is fully valid.
439 @item yellow
440 The signature is valid but additional information was shown regarding the
441 validity of the key.
442 @item red
443 The signature is not valid. 
444 @end table
445
446 @var{displaystring} is a percent-and-plus-encoded string with a short
447 human readable description of the status.  For example
448
449 @smallexample
450 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
451 @end smallexample
452
453 Note that this string needs to fit into an Assuan line and should be
454 short enough to be displayed as short one-liner on the clients window.
455 As usual the encoding of this string is UTF-8 and it should be send in
456 its translated form.
457
458 The server shall send one status line for every signature found on the
459 message.
460
461 @end deffn
462
463
464
465 @c
466 @c M I S C E L L A N E O U S  C O M M A N D S
467 @c
468 @node Miscellaneous Commands
469 @section Miscellaneous Commands
470
471 The server needs to implement the following commands which are not
472 related to a specific command:
473
474 @deffn Command GETINFO @var{what}
475 This is a multi purpose command, commonly used to return a variety of
476 information.  The required subcommands as described by the @var{what}
477 parameter are:
478
479 @table @code
480 @item pid
481 Return the process id of the server in decimal notation using an Assuan
482 data line.
483 @end table
484 @end deffn
485
486
487 @noindent
488 To allow the server to pop up the windows in the correct relation to the
489 client, the client is advised to tell the server by sending the option:
490
491 @deffn {Command option} window-id @var{number} 
492 The @var{number} represents the native window ID of the clients current
493 window.  On Windows systems this is a windows handle (@code{HWND}) and
494 on X11 systems it is the @code{X Window ID}.  The number needs to be
495 given as a hexadecimal value so that it is easier to convey pointer
496 values (e.g. @code{HWND}).
497 @end deffn
498
499
500 @noindent
501 GpgOL features a button to invoke the certificate manager.  To do this
502 it uses the Assuan command:
503
504 @deffn Command START_KEYMANAGER
505 The server shall pop up the main window of the key manager (aka
506 certificate manager).  The client expects that the key manger is brought
507 into the foregound and that this command immediatley returns (does not
508 wait until the key manager has been fully brought up).
509 @end deffn
510
511 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
512 @c
513 @c  M A P I  P r o p e r t i e s
514 @c
515 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
516 @node MAPI Properties
517 @chapter MAPI Properties used by GpgOL
518
519 GpgOL uses a some custom MAPI properties in the named properties range.
520 Thus their actual numbers are determined at runtime and only the names
521 should be used.  The GUID assigned to these properties is
522 @code{31805ab8-3e92-11dc-879c-00061b031004}.
523
524 @table @code
525
526 @item GpgOL Attach Type
527 This is a property of type LONG and used to further describe the
528 attachments created by GpgOL.  These values are used:
529
530   @table @asis
531   @item ATTACHTYPE_MOSS = 1
532   The attachment contains the original MOSS message.  That is either an
533   S/MIME or a PGP/MIME message in its original RFC-2822 format (but only
534   with the relevant MIME parts of the main header).
535
536   @item ATTACHTYPE_FROMMOSS = 2
537   The attachment has been created from the original MOSS attachment.  It
538   will automagically be recreated as needed.  If the atatchment has
539   been created from an encrypted message, it is saved re-encrypted under
540   a non-permanent session key.  This session key is valid as long as the
541   current Outlook porcess exists.
542
543   @item ATTACHTYPE_MOSSTEMPL = 3
544   The attachment has been created in the course of sending a message.
545   @end table
546
547 @item GpgOL Sig Status
548 This is a property of type STRING8 and used to cache the result of the
549 last signature verification.  It is used with the actual message and
550 consists of a single character, a space and a human readable string
551 (utf-8 encoded).  The first character is used as a machine processable
552 flag indicating the status.  These values are defined:
553
554   @table @code
555   @item #
556   The message is not of interest to us.  GpgOL may flag any message with
557   this signature status to avoid extra processing for messages already
558   known not to need any processing by GpgOL.
559
560   @item @@
561   The message has been created and signed or encrypted by GpgOL. 
562  
563   @item ?
564   The signature status has not been checked.  This is for example used
565   if the public key to be used for the verification could not be found.
566
567   @item !
568   The signature verified okay and is deemed to be fully valid.
569
570   @item ~
571   The signature was not fully verified.  This often means that the full
572   result information of the signature verification needs to be
573   considered to decide the actual validity.  Used for example if the
574   signing key has expired
575
576   @item -
577   The signature is bad.  Either this means the message has been tampered
578   with or an intermediate message relay has accidently changed
579   the message (e.g. due to recoding).
580   
581   @end table
582
583 @item GpgOL Protect IV
584 This binary property is used to store the initialization vector of an
585 re-encrypted attachment.  The existence of this property indicates that
586 the attachment has been encrypted under the non-permanent session key.
587
588 @item GpgOL MIME Info
589 This property is of type STRING8 and used to store the MIME structure of
590 the orginal message.  The content are lines of colon delimited fields.
591 The specification has not yet been finished.
592
593 @end table
594
595
596 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
597 @c
598 @c  R e g i s t r y  S  e t t i n g s
599 @c
600 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
601 @node Registry Settings
602 @chapter How GpgOL uses the Registry
603
604 This is a list of registry entries GpgOL knows about. 
605
606 @table @code
607
608 @item HKLM\Software\Gnu\GnuPG:Install Directory
609 This is used by GnuPG to describe the directory where GnupG has been
610 installed.  GpgOL requires this to get the location of the localedir
611 which is used to show translated strings (@file{gpgol.mo}).  It is
612 further used to check whether GnuPG has been installed at all.
613
614 @item HKCU\Software\Gnu\GnuPG:UI Server
615 If the UI server could not be connected, GpgOL tries to start the one
616 given in this entry.  It is assumed that the UI server is stored in the
617 @code{Install Directory} (as described above).  This Registry entry
618 gives the actual command name relative to this directory.  If the key
619 does not exist, is is first searched below @code{HKLM} and then it
620 defaults to @code{bin/kleopatra.exe} (FIXME: The final name will be just
621 @code{kleopatra.exe}).
622
623 In case the UI server requires the socket name as an argument, the
624 placeholder @code{$s} may be used to indicate this.  Due to this feature
625 it is required that all verbatim dollar are too be doubled.  If the
626 actual program name contains spaces the program name nees to be enclosed
627 in quotes.
628
629
630 @end table
631
632
633
634 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
635 @c
636 @c   A P P E N D I X
637 @c 
638 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
639
640 @include gpl.texi
641
642 @c
643 @c  I N D E X E S
644 @c
645 @node Concept Index
646 @unnumbered Concept Index
647 @printindex cp
648 @node Function and Data Index
649 @unnumbered Function and Data Index
650 @printindex fn
651
652 @bye
653
654 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
655 @c
656 @c E D I T O R ' S   A T T I C
657 @c 
658 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
659
660 What about the message class mangling?
661
662 * On receiving a new message GpgOL checks the MAPI message class
663   property of the message and if this is an S/MIME message class
664   ("IPM.Note.SMIME"), it is changed to a GpgOL specific one
665   ("IPM.Note.GpgOL").  This change is required so that OL does not not
666   apply its own S/MIME handler to the message but leaves it unchanged in
667   the message store.
668
669 * For ease of implementarion the same thing applies to PGP messgaes,
670   although OL would not touch these messages.
671
672 * When reading a message GpgOL quickly checks the message class and if
673   it is "IPM.Note.GpgOL" it will hook itself into the code path and
674   decrypt/verify the message.
675
676 * Messages already in the message store before GpgOL was installed are
677   handled diffwerently: Here an Outlook specific event is used to change
678   the message class when browsing the messages folder.  This code path
679   is not fully ready as it requires the installation of an ECF(ile)
680   which has to be done manually as of now.
681
682 * If GpgOL is deinstalled, the existing S/MIME messages can't be
683   decrypted or verified by Outlook's internal S/MIME support.
684   Multipart/signed messages are still readable, though.  We plan to add
685   a little tool for changing the GpgOL message classes back to
686   "IPM.Note.SMIME" which in turn allows using internal S/MIME support
687   again.
688
689
690
691
692 @c Local Variables:
693 @c coding: latin-1
694 @c End: