8001d9fce813b87cc6de6c46c639e1403abd69d4
[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
13 @c Unify some of the indices.
14 @syncodeindex tp fn
15 @syncodeindex pg fn
16
17 @copying
18 This is @cite{The GpgOL Technical Manual} for @acronym{GpgOL} (version
19 @value{VERSION}, @value{UPDATED-MONTH}).
20
21 @iftex
22 Published by g10 Code GmbH@*
23 Hüttenstr. 61@*
24 40699 Erkrath, Germany
25 @end iftex
26
27 Copyright @copyright{} 2007 g10 Code GmbH
28
29 @quotation
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU General Public License as published by the
32 Free Software Foundation; either version 3 of the License, or (at your
33 option) any later version. The text of the license can be found in the
34 section entitled ``Copying''.
35 @end quotation
36 @end copying
37
38 @c
39 @c Titlepage
40 @c
41 @setchapternewpage odd
42 @titlepage 
43 @title The GpgOL Technical Manual
44 @subtitle Version @value{VERSION}
45 @subtitle @value{UPDATED-MONTH}
46
47 @sp 3
48
49 @sp 3
50
51 @author Werner Koch (@email{wk@@gnupg.org})
52
53 @page
54 @vskip 0pt plus 1filll
55 @insertcopying
56 @end titlepage
57
58 @ifnothtml
59 @contents
60 @page
61 @end ifnothtml
62
63 @c @ifhtml
64 @c @center @image{logo}
65 @c @end ifhtml
66
67 @ifnottex
68 @node Top
69 @top 
70
71 @insertcopying
72
73 @noindent
74 This file documents @acronym{GpgOL}; a GnuPG plugin for Microsoft's
75 Outlook MUA.
76 @end ifnottex
77
78
79 @menu
80 * Introduction::                How to use this manual.
81 * Assuan Protocol::             Description of the UI server protocol.
82
83 Appendices
84
85 * Copying::                     The GNU General Public License says how you
86                                 can copy and share this manual.
87
88 Indices
89
90 * Concept Index::               Index of concepts and programs.
91 * Function and Data Index::     Index of functions, variables and data types.
92
93 @end menu
94
95 @ifhtml
96 @page
97 @summarycontents
98 @contents
99 @end ifhtml
100
101 @c
102 @c  I N T R O
103 @c
104 @node Introduction
105 @chapter Introduction
106 Bla bla
107
108
109 @c
110 @c  P R O T O C O L  D E S C R I P T I O N
111 @c
112 @node Assuan Protocol
113 @chapter Description of the UI Server Protocol
114
115 This section describes the protocol used between @acronym{GpgOL} and the
116 User Interface Server (UI server).  All cryptographic operations are
117 done by this server and the server is responsible for all dialogs.  If a
118 a server is not available, @acronym{GpgOL} can only use a very limited
119 internal crypto server.
120
121 We assume that the connection has already been established; see the
122 Assuan manual for details.
123
124 @menu
125 * ENCRYPT::                  Encrypt a message.
126 * SIGN::                     Sign a message.
127 * DECRYPT::                  Decrypt a message.
128 * VERIFY::                   Verify a message.
129 * Miscellaneous Commands::   Commands not related to a specific operation.
130 @end menu
131
132
133
134 @node ENCRYPT
135 @section Encrypt a Message
136
137 Before encryption can be done the recipients must be set using the
138 command:
139
140 @deffn Command RECIPIENT @var{string}
141
142 Set the recipient for the encryption.  @var{string} is an RFC-2822
143 recipient name.  This command may or may not check the recipient for
144 validity right away; if it does not all recipients are expected to be
145 checked at the time of the @code{ENCRYPT} command.  All @code{RECIPIENT}
146 commands are cumulative until a successful @code{ENCRYPT} command or
147 until a @code{RESET} command.  Linefeeds are obviously not allowed in
148 @var{string} and should be folded into spaces (which are equivalent).
149 @end deffn
150
151 @noindent
152 To tell the server the source and destination of the data, the next two
153 commands are to be used:
154
155 @deffn Command INPUT FD=@var{n}
156 Set the file descriptor for the message to be encrypted to @var{n}.  The
157 message send to the server is binary encoded. 
158
159 GpgOL is a Windows only program, thus @var{n} is not a libc file
160 descriptor but a regular system handle.  Given that the Assuan
161 connection works over a socket, it is not possible to use regular
162 inheritance to make the file descriptor available to the server.
163 Thus @code{DuplicateHandle} needs to be used to duplicate a handle
164 to the server process.  This is the reason that the server needs to
165 implement the @code{GETINFO pid} command.  Sending this command a second
166 time replaces the file descriptor set by the last one.
167 @c If @var{n} is not given, this commands uses the
168 @c %last file descriptor passed to the application.
169 @c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
170 @c %Libassuan manual}, on how to do descriptor passing.
171 @end deffn
172
173 @deffn Command OUTPUT FD=@var{n}
174 Set the file descriptor to be used for the output (i.e. the encrypted
175 message) to @var{n}.  For OpenPGP, the output needs to be ASCII armored;
176 for CMS, the output needs to be Base-64 encoded.  For details on the
177 file descriptor, see the @code{INPUT} command.
178 @end deffn
179
180 @noindent  
181 The setting of the recipients, the data source and destination may
182 happen in any order, even intermixed.  If this has been done the actual
183 encryption operation is called using:
184
185 @deffn Command ENCRYPT -@w{}-protocol=@var{name}
186
187 This command reads the plaintext from the file descriptor set by the
188 @code{INPUT} command, encrypts it and writes the ciphertext to the file
189 descriptor set by the @code{OUTPUT} command.  The server may (and
190 should) overlap reading and writing.  The recipients used for the
191 encryption are all the recipients set so far.  If any recipient is not
192 usable the server should take appropriate measures to notify the user
193 about the problem and may cancel the operation by returning an error
194 code.  The used file descriptors are a void after this command; the
195 recipient list is only cleared if the server returns success.
196
197 @noindent
198 Because GpgOL uses a streaming mode of operation the server is not
199 allowed to auto select the protocol and must obey to the mandatory
200 @var{protocol} parameter:
201
202 @table @code
203 @item OpenPGP
204 Use the OpenPGP protocol (RFC-2440).
205 @item CMS
206 Use the CMS (PKCS#7) protocol (RFC-3852).
207 @end table
208
209 @end deffn
210
211
212 @node SIGN
213 @section Sign a Message
214
215 The server needs to implement opaque signing as well as detached
216 signing.  Due to the nature of OpenPGP message it is always required to
217 send the entire message to the server; sending just the hash is not
218 possible.  The following two commands are required to set the input and
219 output file descriptors:
220
221 @deffn Command INPUT FD=@var{n}
222 Set the file descriptor for the message to be signed to @var{n}.  The
223 message send to the server is binary encoded.  For details on the file
224 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
225 section.
226 @end deffn
227
228 @deffn Command OUTPUT FD=@var{n}
229 Set the file descriptor to be used for the output.  The output is either
230 the complete signed message or in case of a detached signature just that
231 detached signature.  For OpenPGP, the output needs to be ASCII armored;
232 for CMS, the output needs to be Base-64 encoded.  For details on the
233 file descriptor, see the @code{INPUT} command.
234 @end deffn
235
236 @noindent
237 To allow the server the selection of a non-default signing key the
238 client may optionally use the command:
239
240 @deffn Command SENDER @var{email}
241 @var{email} is the plain ASCII encoded address ("addr-spec" as per
242 RFC-2822) enclosed in angle brackets.  The address set with this command
243 is valid until a successful @code{SIGN} command or until a @code{RESET}
244 command.  A second command overrides the effect of the first one; if
245 @var{email} is not given the server shall use the default signing key.
246 @end deffn
247
248 @noindent
249 The signing operation is then initiated by:
250
251 @deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] 
252 Sign the data set with the @code{INPUT} command and write it to the sink
253 set by OUTPUT.  @var{name} is the signing protocol used for the
254 message. For a description of the allowed protocols see the
255 @code{ENCRYPT} command.  With option @code{--detached} given, a detached
256 signature is created; this is actually the usual way the command is
257 used.
258 @end deffn
259
260 @noindent
261 The client expects the server to send at least this status information
262 before the final OK response:
263
264 @deffn {Status line} MICALG @var{string}
265 The @var{string} represents the hash algorithm used to create the
266 signature. It is used with MOSS style signature messaged and defined by
267 PGP/MIME (RFC-3156) and S/MIME (RFC-3851).  The GPGME library has a
268 supporting function @code{gpgme_hash_algo_name} to return the algorithm
269 name as a string.  This string needs to be lowercased and for OpenPGP
270 prefixed with "@code{pgp-}".
271 @end deffn
272
273
274
275 @node DECRYPT
276 @section Decrypt a Message
277
278 Decryption may include the verification of OpenPGP messages.  This is
279 due to the often used combined signing/encryption modus of OpenPGP.  The
280 client may pass an option to the server to inhibit the signature
281 verification.  The following two commands are required to set the input
282 and output file descriptors:
283
284 @deffn Command INPUT FD=@var{n}
285 Set the file descriptor for the message to be decrypted to @var{n}.  The
286 message send to the server is either binary encoded or --- in the case
287 of OpenPGP --- ASCII armored.  For details on the file descriptor, see
288 the description of @code{INPUT} in the @code{ENCRYPT} section.
289 @end deffn
290
291 @deffn Command OUTPUT FD=@var{n}
292 Set the file descriptor to be used for the output. The output is binary
293 encoded. For details on the file descriptor, see the description of
294 @code{INPUT} in the @code{ENCRYPT} section.
295 @end deffn
296
297 @noindent
298 The decryption is started with the command:
299
300 @deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
301 @var{name} is the encryption protocol used for the message. For a
302 description of the allowed protocols see the @code{ENCRYPT} command.
303 This argument is mandatory.  If the option @option{--no-verify} is given,
304 the server should not try to verify a signature, in case the input data
305 is an OpenPGP combined message.
306 @end deffn
307
308
309 @node VERIFY
310 @section Verify a Message
311
312 The server needs to support the verification of opaque signatures as
313 well as detached signatures.  The kind of input sources controls what
314 kind message is to be verified.
315
316 @deffn Command MESSAGE FD=@var{n}
317 This command is used with detached signatures to set the file descriptor
318 for the signed data to @var{n}. The data is binary encoded (used
319 verbatim).  For details on the file descriptor, see the description of
320 @code{INPUT} in the @code{ENCRYPT} section.
321 @end deffn
322
323 @deffn Command INPUT FD=@var{n}
324 Set the file descriptor for the opaque message or the signature part of
325 a detached signature to @var{n}.  The message send to the server is
326 either binary encoded or -- in the case of OpenPGP -- ASCII armored.
327 For details on the file descriptor, see the description of @code{INPUT}
328 in the @code{ENCRYPT} section.
329 @end deffn
330
331 @deffn Command OUTPUT FD=@var{n}
332 Set the file descriptor to be used for the output. The output is binary
333 encoded and only used for opaque signatures.  For details on the file
334 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
335 section.
336 @end deffn
337
338 @noindent
339 The verification is then started using:
340
341 @deffn Command VERIFY -@w{}-protocol=@var{name}
342 @var{name} is the signing protocol used for the message. For a
343 description of the allowed protocols see the @code{ENCRYPT} command.
344 This argument is mandatory.  Depending on the combination of
345 @code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
346 to select the appropriate verification mode:
347
348 @table @asis
349 @item MESSAGE and INPUT
350 This indicates a detached signature.  Output data is not applicable.
351 @item INPUT 
352 This indicates an opaque signature.  As no output command has been given,
353 the server is only required to check the signature.
354 @item INPUT and OUTPUT
355 This indicates an opaque signature.  The server shall write the signed
356 data to the file descriptor set by the output command.  This data shall
357 even be written if the signatures can't be verified.
358 @end table
359 @end deffn
360
361 @noindent
362 The client expects the server to send at least this status information
363 before the final OK response:
364
365 @deffn {Status line} SIGSTATUS @var{flag} @var{displaystring}
366 Returns the status for the signature and a short string explaining the
367 status.  Valid values for @var{flag} are:
368
369 @table @code
370 @item none
371 The message has a signature but it could not not be verified due to a
372 missing key.
373 @item green
374 The signature is fully valid.
375 @item yellow
376 The signature is valid but additional information was shown regarding the
377 validity of the key.
378 @item red
379 The signature is not valid. 
380 @end table
381
382 @var{displaystring} is a percent-and-plus-encoded string with a short
383 human readable description of the status.  For example
384
385 @smallexample
386 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
387 @end smallexample
388
389 Note that this string needs to fit into an Assuan line and should be
390 short enough to be displayed as short one-liner on the clients window.
391 As usual the encoding of this string is UTF-8 and it should be send in
392 its translated form.
393
394 The server shall send one status line for every signature found on the
395 message.
396
397 @end deffn
398
399
400
401 @c
402 @c M I S C E L L A N E O U S  C O M M A N D S
403 @c
404 @node Miscellaneous Commands
405 @section Miscellaneous Commands
406
407 The server needs to implement the following commands which are not
408 related to a specific command:
409
410 @deffn Command GETINFO @var{what}
411 This is a multi purpose command, commonly used to return a variety of
412 information.  The required subcommands as described by the @var{what}
413 parameter are:
414
415 @table @code
416 @item pid
417 Return the process id of the server in decimal notation using an Assuan
418 data line.
419 @end table
420 @end deffn
421
422
423 @noindent
424 To allow the server to pop up the windows in the correct relation to the
425 client, the client is advised to tell the server by sending the option:
426
427 @deffn {Command option} window-id @var{number} 
428 The @var{number} represents the native window ID of the clients current
429 window.  On Windows systems this is a windows handle (@code{HWND}) and
430 on X11 systems it is the @code{X Window ID}.  The number needs to be
431 given as a hexadecimal value so that it is easier to convey pointer
432 values (e.g. @code{HWND}).
433 @end deffn
434
435
436 @include gpl.texi
437
438 @c
439 @c  I N D E X E S
440 @c
441 @node Concept Index
442 @unnumbered Concept Index
443 @printindex cp
444 @node Function and Data Index
445 @unnumbered Function and Data Index
446 @printindex fn
447
448 @bye
449
450 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
451 @c
452 @c E D I T O R ' S   A T T I C
453 @c 
454 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
455
456 What about the message class mangling?
457
458 * On receiving a new message GpgOL checks the MAPI message class
459   property of the message and if this is an S/MIME message class
460   ("IPM.Note.SMIME"), it is changed to a GpgOL specific one
461   ("IPM.Note.GpgOL").  This change is required so that OL does not not
462   apply its own S/MIME handler to the message but leaves it unchanged in
463   the message store.
464
465 * For ease of implementarion the same thing applies to PGP messgaes,
466   although OL would not touch these messages.
467
468 * When reading a message GpgOL quickly checks the message class and if
469   it is "IPM.Note.GpgOL" it will hook itself into the code path and
470   decrypt/verify the message.
471
472 * Messages already in the message store before GpgOL was installed are
473   handled diffwerently: Here an Outlook specific event is used to change
474   the message class when browsing the messages folder.  This code path
475   is not fully ready as it requires the installation of an ECF(ile)
476   which has to be done manually as of now.
477
478 * If GpgOL is deinstalled, the existing S/MIME messages can't be
479   decrypted or verified by Outlook's internal S/MIME support.
480   Multipart/signed messages are still readable, though.  We plan to add
481   a little tool for changing the GpgOL message classes back to
482   "IPM.Note.SMIME" which in turn allows using internal S/MIME support
483   again.
484
485
486
487
488 @c Local Variables:
489 @c coding: latin-1
490 @c End: