2008-09-16 Marcus Brinkmann <marcus@g10code.com>
[gpgme.git] / doc / uiserver.texi
1 @c uiserver.texi                    -*- mode: texinfo; coding: latin-1; -*-
2 @c Specification of the UI server protocol.
3 @c To be included by gpgme.texi
4
5 @node UI Server Protocol
6 @appendix The GnuPG UI Server Protocol
7 @cindex UI server
8 @cindex user interface server
9
10
11 This section specifies the protocol used between clients and a User
12 Interface Server (UI server).  This protocol helps to build a system
13 where all cryptographic operations are done by a server and the server
14 is responsible for all dialogs.  Although @acronym{GPGME} has no direct
15 support for this protocol it is believed that servers will utilize the
16 @acronym{GPGME} library; thus having the specification included in this
17 manual is an appropriate choice.  This protocol should be referenced as
18 `The GnuPG UI Server Protocol'.
19
20 @noindent
21 A server needs to implement these commands:@footnote{In all examples we
22 assume that the connection has already been established; see the Assuan
23 manual for details.}
24
25 @menu
26 * UI Server Encrypt::                Encrypt a message.
27 * UI Server Sign::                   Sign a message.
28 * UI Server Decrypt::                Decrypt a message.
29 * UI Server Verify::                 Verify a message.
30 * UI Server Set Input Files::        Specifying the input files to operate on.
31 * UI Server Sign/Encrypt Files::     Encrypting and signing files.
32 * UI Server Verify/Decrypt Files::   Decrypting and verifying files.
33 * UI Server Import/Export Keys::     Managing certificates.
34 * UI Server Checksum Files::         Create and verify checksums for files.
35 * Miscellaneous UI Server Commands::   Commands not related to a specific operation.
36 @end menu
37
38
39
40 @node UI Server Encrypt
41 @section UI Server: Encrypt a Message
42
43 Before encryption can be done the recipients must be set using the
44 command:
45
46 @deffn Command RECIPIENT @var{string}
47
48 Set the recipient for the encryption.  @var{string} is an RFC-2822
49 recipient name ("mailbox" as per section 3.4).  This command may or may
50 not check the recipient for validity right away; if it does not all
51 recipients are expected to be checked at the time of the @code{ENCRYPT}
52 command.  All @code{RECIPIENT} commands are cumulative until a
53 successful @code{ENCRYPT} command or until a @code{RESET} command.
54 Linefeeds are obviously not allowed in @var{string} and should be folded
55 into spaces (which are equivalent).
56 @end deffn
57
58 @noindent
59 To tell the server the source and destination of the data, the next two
60 commands are to be used:
61
62 @deffn Command INPUT FD=@var{n}
63 Set the file descriptor for the message to be encrypted to @var{n}.  The
64 message send to the server is binary encoded. 
65
66 GpgOL is a Windows only program, thus @var{n} is not a libc file
67 descriptor but a regular system handle.  Given that the Assuan
68 connection works over a socket, it is not possible to use regular
69 inheritance to make the file descriptor available to the server.
70 Thus @code{DuplicateHandle} needs to be used to duplicate a handle
71 to the server process.  This is the reason that the server needs to
72 implement the @code{GETINFO pid} command.  Sending this command a second
73 time replaces the file descriptor set by the last one.
74 @c If @var{n} is not given, this commands uses the
75 @c %last file descriptor passed to the application.
76 @c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
77 @c %Libassuan manual}, on how to do descriptor passing.
78 @end deffn
79
80 @deffn Command OUTPUT FD=@var{n}
81 Set the file descriptor to be used for the output (i.e. the encrypted
82 message) to @var{n}.  For OpenPGP, the output needs to be ASCII armored;
83 for CMS, the output needs to be Base-64 encoded.  For details on the
84 file descriptor, see the @code{INPUT} command.
85 @end deffn
86
87 @noindent  
88 The setting of the recipients, the data source and destination may
89 happen in any order, even intermixed.  If this has been done the actual
90 encryption operation is called using:
91
92 @deffn Command ENCRYPT -@w{}-protocol=@var{name}
93
94 This command reads the plaintext from the file descriptor set by the
95 @code{INPUT} command, encrypts it and writes the ciphertext to the file
96 descriptor set by the @code{OUTPUT} command.  The server may (and
97 should) overlap reading and writing.  The recipients used for the
98 encryption are all the recipients set so far.  If any recipient is not
99 usable the server should take appropriate measures to notify the user
100 about the problem and may cancel the operation by returning an error
101 code.  The used file descriptors are void after this command; the
102 recipient list is only cleared if the server returns success.
103
104 @noindent
105 Because GpgOL uses a streaming mode of operation the server is not
106 allowed to auto select the protocol and must obey to the mandatory
107 @var{protocol} parameter:
108
109 @table @code
110 @item OpenPGP
111 Use the OpenPGP protocol (RFC-2440).
112 @item CMS
113 Use the CMS (PKCS#7) protocol (RFC-3852).
114 @end table
115
116 @end deffn
117
118 To support automagically selection of the protocol depending on the
119 selected keys, the server MAY implement the command:
120
121 @deffn Command PREP_ENCRYPT [-@w{}-protocol=@var{name}]
122
123 This commands considers all recipients set so far and decides whether it
124 is able to take input and start the actual decryption.  This is kind of
125 a dry-run @command{ENCRYPT} without requiring or using the input and
126 output file descriptors.  The server shall cache the result of any user
127 selection to avoid asking this again when the actual @command{ENCRYPT}
128 command is send.  The @option{--protocol} option is optional; if it is
129 not given, the server should allow the user to select the protocol to be
130 used based on the recipients given or by any other means.
131
132 If this command is given again before a successful @command{ENCRYPT}
133 command, the second one takes effect. 
134
135 Before sending the OK response the server shall tell the client the
136 protocol to be used (either the one given by the argument or the one
137 selected by the user) by means of a status line:
138 @end deffn
139
140 @deffn {Status line} PROTOCOL @var{name}
141 Advise the client to use the protocol @var{name} for the
142 @command{ENCRYPT} command.  The valid protocol names are listed under
143 the description of the @command{ENCRYPT} command.  The server shall emit
144 exactly one PROTOCOL status line.
145 @end deffn
146
147 @noindent
148 Here is an example of a complete encryption sequence; client lines are
149 indicated by a @sc{c:}, server responses by @sc{c:}:
150
151 @smallexample
152 @group
153   @clnt RESET
154   @srvr OK
155   @clnt RECIPIENT foo@@example.net
156   @srvr OK
157   @clnt RECIPIENT bar@@example.com
158   @srvr OK
159   @clnt PREP_ENCRYPT
160   @srvr S PROTOCOL OpenPGP
161   @srvr OK
162   @clnt INPUT FD=17
163   @srvr OK
164   @clnt OUTPUT FD=18
165   @srvr OK
166   @clnt ENCRYPT
167   @srvr OK
168 @end group
169 @end smallexample
170
171
172
173 @node UI Server Sign
174 @section UI Server: Sign a Message
175
176 The server needs to implement opaque signing as well as detached
177 signing.  Due to the nature of OpenPGP messages it is always required to
178 send the entire message to the server; sending just the hash is not
179 possible.  The following two commands are required to set the input and
180 output file descriptors:
181
182 @deffn Command INPUT FD=@var{n}
183 Set the file descriptor for the message to be signed to @var{n}.  The
184 message send to the server is binary encoded.  For details on the file
185 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
186 section.
187 @end deffn
188
189 @deffn Command OUTPUT FD=@var{n}
190 Set the file descriptor to be used for the output.  The output is either
191 the complete signed message or in case of a detached signature just that
192 detached signature.  For OpenPGP, the output needs to be ASCII armored;
193 for CMS, the output needs to be Base-64 encoded.  For details on the
194 file descriptor, see the @code{INPUT} command.
195 @end deffn
196
197 @noindent
198 To allow the server the selection of a non-default signing key the
199 client may optionally use the @code{SENDER} command, see @ref{command
200 SENDER}.
201
202 @noindent
203 The signing operation is then initiated by:
204
205 @deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] 
206 Sign the data set with the @code{INPUT} command and write it to the sink
207 set by OUTPUT.  @var{name} is the signing protocol used for the
208 message. For a description of the allowed protocols see the
209 @code{ENCRYPT} command.  With option @code{--detached} given, a detached
210 signature is created; this is actually the usual way the command is
211 used.
212 @end deffn
213
214 @noindent
215 The client expects the server to send at least this status information
216 before the final OK response:
217
218 @deffn {Status line} MICALG @var{string}
219 The @var{string} represents the hash algorithm used to create the
220 signature. It is used with MOSS style signature messages and defined by
221 PGP/MIME (RFC-3156) and S/MIME (RFC-3851).  The GPGME library has a
222 supporting function @code{gpgme_hash_algo_name} to return the algorithm
223 name as a string.  This string needs to be lowercased and for OpenPGP
224 prefixed with "@code{pgp-}".
225 @end deffn
226
227
228
229 @node UI Server Decrypt
230 @section UI Server: Decrypt a Message
231
232 Decryption may include the verification of OpenPGP messages.  This is
233 due to the often used combined signing/encryption modus of OpenPGP.  The
234 client may pass an option to the server to inhibit the signature
235 verification.  The following two commands are required to set the input
236 and output file descriptors:
237
238 @deffn Command INPUT FD=@var{n}
239 Set the file descriptor for the message to be decrypted to @var{n}.  The
240 message send to the server is either binary encoded or --- in the case
241 of OpenPGP --- ASCII armored.  For details on the file descriptor, see
242 the description of @code{INPUT} in the @code{ENCRYPT} section.
243 @end deffn
244
245 @deffn Command OUTPUT FD=@var{n}
246 Set the file descriptor to be used for the output. The output is binary
247 encoded. For details on the file descriptor, see the description of
248 @code{INPUT} in the @code{ENCRYPT} section.
249 @end deffn
250
251 @noindent
252 The decryption is started with the command:
253
254 @deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
255 @var{name} is the encryption protocol used for the message. For a
256 description of the allowed protocols see the @code{ENCRYPT} command.
257 This argument is mandatory.  If the option @option{--no-verify} is given,
258 the server should not try to verify a signature, in case the input data
259 is an OpenPGP combined message.
260 @end deffn
261
262
263 @node UI Server Verify
264 @section UI Server: Verify a Message
265
266 The server needs to support the verification of opaque signatures as
267 well as detached signatures.  The kind of input sources controls what
268 kind message is to be verified. 
269
270 @deffn Command MESSAGE FD=@var{n}
271 This command is used with detached signatures to set the file descriptor
272 for the signed data to @var{n}. The data is binary encoded (used
273 verbatim).  For details on the file descriptor, see the description of
274 @code{INPUT} in the @code{ENCRYPT} section.
275 @end deffn
276
277 @deffn Command INPUT FD=@var{n}
278 Set the file descriptor for the opaque message or the signature part of
279 a detached signature to @var{n}.  The message send to the server is
280 either binary encoded or -- in the case of OpenPGP -- ASCII armored.
281 For details on the file descriptor, see the description of @code{INPUT}
282 in the @code{ENCRYPT} section.
283 @end deffn
284
285 @deffn Command OUTPUT FD=@var{n}
286 Set the file descriptor to be used for the output. The output is binary
287 encoded and only used for opaque signatures.  For details on the file
288 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
289 section.
290 @end deffn
291
292 @noindent
293 The verification is then started using:
294
295 @deffn Command VERIFY -@w{}-protocol=@var{name} [-@w{}-silent]
296 @var{name} is the signing protocol used for the message. For a
297 description of the allowed protocols see the @code{ENCRYPT} command.
298 This argument is mandatory.  Depending on the combination of
299 @code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
300 to select the appropriate verification mode:
301
302 @table @asis
303 @item MESSAGE and INPUT
304 This indicates a detached signature.  Output data is not applicable.
305 @item INPUT 
306 This indicates an opaque signature.  As no output command has been given,
307 the server is only required to check the signature.
308 @item INPUT and OUTPUT
309 This indicates an opaque signature.  The server shall write the signed
310 data to the file descriptor set by the output command.  This data shall
311 even be written if the signatures can't be verified.
312 @end table
313 @end deffn
314
315 With @option{--silent} the server shall not display any dialog; this is
316 for example used by the client to get the content of opaque signed
317 messages. The client expects the server to send at least this status
318 information before the final OK response:
319
320 @deffn {Status line} SIGSTATUS @var{flag} @var{displaystring}
321 Returns the status for the signature and a short string explaining the
322 status.  Valid values for @var{flag} are:
323
324 @table @code
325 @item none
326 The message has a signature but it could not not be verified due to a
327 missing key.
328 @item green
329 The signature is fully valid.
330 @item yellow
331 The signature is valid but additional information was shown regarding the
332 validity of the key.
333 @item red
334 The signature is not valid. 
335 @end table
336
337 @var{displaystring} is a percent-and-plus-encoded string with a short
338 human readable description of the status.  For example
339
340 @smallexample
341 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
342 @end smallexample
343
344 Note that this string needs to fit into an Assuan line and should be
345 short enough to be displayed as short one-liner on the clients window.
346 As usual the encoding of this string is UTF-8 and it should be send in
347 its translated form.
348
349 The server shall send one status line for every signature found on the
350 message.
351
352
353 @end deffn
354
355
356 @node UI Server Set Input Files
357 @section UI Server: Specifying the input files to operate on.
358
359 All file related UI server commands operate on a number of input files
360 or directories, specified by one or more @code{FILE} commands:
361
362 @deffn Command FILE @var{name} [--continued]
363 Add the file or directory @var{name} to the list of pathnames to be
364 processed by the server.  The parameter @var{name} must be an absolute
365 path name (including the drive letter) and is percent espaced (in
366 particular, the characters %, = and white space characters are always
367 escaped).  The option @code{--continued} is present for all but the
368 last @code{FILE} command.
369 @end deffn
370
371
372 @node UI Server Sign/Encrypt Files
373 @section UI Server: Encrypting and signing files.
374
375 First, the input files need to be specified by one or more
376 @code{FILE} commands.  Afterwards, the actual operation is requested:
377
378 @deffn Command ENCRYPT_FILES --nohup
379 @deffnx Command SIGN_FILES --nohup
380 @deffnx Command ENCRYPT_SIGN_FILES --nohup
381 Request that the files specified by @code{FILE} are encrypted and/or
382 signed.  The command selects the default action.  The UI server may
383 allow the user to change this default afterwards interactively, and
384 even abort the operation or complete it only on some of the selected
385 files and directories.
386
387 What it means to encrypt or sign a file or directory is specific to
388 the preferences of the user, the functionality the UI server provides,
389 and the selected protocol.  Typically, for each input file a new file
390 is created under the original filename plus a protocol specific
391 extension (like @code{.gpg} or @code{.sig}), which contain the
392 encrypted/signed file or a detached signature.  For directories, the
393 server may offer multiple options to the user (for example ignore or
394 process recursively).
395
396 The @code{ENCRYPT_SIGN_FILES} command requests a combined sign and
397 encrypt operation.  It may not be available for all protocols (for
398 example, it is available for OpenPGP but not for CMS).
399
400 The option @code{--nohup} is mandatory.  It is currently unspecified
401 what should happen if @code{--nohup} is not present.  Because
402 @code{--nohup} is present, the server always returns @code{OK}
403 promptly, and completes the operation asynchronously.
404 @end deffn
405
406
407 @node UI Server Verify/Decrypt Files
408 @section UI Server: Decrypting and verifying files.
409
410 First, the input files need to be specified by one or more
411 @code{FILE} commands.  Afterwards, the actual operation is requested:
412
413 @deffn Command DECRYPT_FILES --nohup
414 @deffnx Command VERIFY_FILES --nohup
415 @deffnx Command DECRYPT_VERIFY_FILES --nohup
416 Request that the files specified by @code{FILE} are decrypted and/or
417 verified.  The command selects the default action.  The UI server may
418 allow the user to change this default afterwards interactively, and
419 even abort the operation or complete it only on some of the selected
420 files and directories.
421
422 What it means to decrypt or verify a file or directory is specific to
423 the preferences of the user, the functionality the UI server provides,
424 and the selected protocol.  Typically, for decryption, a new file is
425 created for each input file under the original filename minus a
426 protocol specific extension (like @code{.gpg}) which contains the
427 original plaintext.  For verification a status is displayed for each
428 signed input file, indicating if it is signed, and if yes, if the
429 signature is valid.  For files that are signed and encrypted, the
430 @code{VERIFY} command transiently decrypts the file to verify the
431 enclosed signature.  For directories, the server may offer multiple
432 options to the user (for example ignore or process recursively).
433
434 The option @code{--nohup} is mandatory.  It is currently unspecified
435 what should happen if @code{--nohup} is not present.  Because
436 @code{--nohup} is present, the server always returns @code{OK}
437 promptly, and completes the operation asynchronously.
438 @end deffn
439
440
441 @node UI Server Import/Export Keys
442 @section UI Server: Managing certificates.
443
444 First, the input files need to be specified by one or more
445 @code{FILE} commands.  Afterwards, the actual operation is requested:
446
447 @deffn Command IMPORT_FILES --nohup
448 Request that the certificates contained in the files specified by
449 @code{FILE} are imported into the local certificate databases.
450
451 For directories, the server may offer multiple options to the user
452 (for example ignore or process recursively).
453
454 The option @code{--nohup} is mandatory.  It is currently unspecified
455 what should happen if @code{--nohup} is not present.  Because
456 @code{--nohup} is present, the server always returns @code{OK}
457 promptly, and completes the operation asynchronously.
458 @end deffn
459
460 FIXME: It may be nice to support an @code{EXPORT} command as well,
461 which is enabled by the context menu of the background of a directory.
462
463
464 @node UI Server Checksum Files
465 @section UI Server: Create and verify checksums for files.
466
467 First, the input files need to be specified by one or more
468 @code{FILE} commands.  Afterwards, the actual operation is requested:
469
470 @deffn Command CHECKSUM_CREATE_FILES --nohup
471 Request that checksums are created for the files specifed by
472 @code{FILE}.  The choice of checksum algorithm and the destination
473 storage and format for the created checksums depend on the preferences
474 of the user and the functionality provided by the UI server.  For
475 directories, the server may offer multiple options to the user (for
476 example ignore or process recursively).
477
478 The option @code{--nohup} is mandatory.  It is currently unspecified
479 what should happen if @code{--nohup} is not present.  Because
480 @code{--nohup} is present, the server always returns @code{OK}
481 promptly, and completes the operation asynchronously.
482 @end deffn
483
484
485 @deffn Command CHECKSUM_VERIFY_FILES --nohup
486 Request that checksums are created for the files specifed by
487 @code{FILE} and verified against previously created and stored
488 checksums.  The choice of checksum algorithm and the source storage
489 and format for previously created checksums depend on the preferences
490 of the user and the functionality provided by the UI server.  For
491 directories, the server may offer multiple options to the user (for
492 example ignore or process recursively).
493
494 If the source storage of previously created checksums is available to
495 the user through the Windows shell, this command may also accept such
496 checksum files as @code{FILE} arguments.  In this case, the UI server
497 should instead verify the checksum of the referenced files as if they
498 were given as INPUT files.
499
500 The option @code{--nohup} is mandatory.  It is currently unspecified
501 what should happen if @code{--nohup} is not present.  Because
502 @code{--nohup} is present, the server always returns @code{OK}
503 promptly, and completes the operation asynchronously.
504 @end deffn
505
506
507
508
509 @c
510 @c M I S C E L L A N E O U S  C O M M A N D S
511 @c
512 @node Miscellaneous UI Server Commands
513 @section Miscellaneous UI Server Commands
514
515 The server needs to implement the following commands which are not
516 related to a specific command:
517
518 @deffn Command GETINFO @var{what}
519 This is a multi purpose command, commonly used to return a variety of
520 information.  The required subcommands as described by the @var{what}
521 parameter are:
522
523 @table @code
524 @item pid
525 Return the process id of the server in decimal notation using an Assuan
526 data line.
527 @end table
528 @end deffn
529
530
531 @noindent
532 To allow the server to pop up the windows in the correct relation to the
533 client, the client is advised to tell the server by sending the option:
534
535 @deffn {Command option} window-id @var{number} 
536 The @var{number} represents the native window ID of the clients current
537 window.  On Windows systems this is a windows handle (@code{HWND}) and
538 on X11 systems it is the @code{X Window ID}.  The number needs to be
539 given as a hexadecimal value so that it is easier to convey pointer
540 values (e.g. @code{HWND}).
541 @end deffn
542
543
544 @noindent
545 A client may want to fire up the certificate manager of the server.  To
546 do this it uses the Assuan command:
547
548 @deffn Command START_KEYMANAGER
549 The server shall pop up the main window of the key manager (aka
550 certificate manager).  The client expects that the key manager is brought
551 into the foregound and that this command immediatley returns (does not
552 wait until the key manager has been fully brought up).
553 @end deffn
554
555 @noindent
556 A client may want to fire up the configuration dialog of the server.  To
557 do this it uses the Assuan command:
558
559 @deffn Command START_CONFDIALOG
560 The server shall pop up its configuration dialog.  The client expects
561 that this dialog is brought into the foregound and that this command
562 immediatley returns (i.e. it does not wait until the dialog has been
563 fully brought up).
564 @end deffn
565
566 @anchor{command SENDER}
567 @noindent
568 When doing an operation on a mail, it is useful to let the server know
569 the address of the sender:
570
571 @deffn Command SENDER [-@w{}-info] @var{email}
572 @var{email} is the plain ASCII encoded address ("addr-spec" as per
573 RFC-2822) enclosed in angle brackets.  The address set with this command
574 is valid until a successful completion of the operation or until a
575 @code{RESET} command.  A second command overrides the effect of the
576 first one; if @var{email} is not given and @option{--info} is not used,
577 the server shall use the default signing key.
578
579 If option @option{--info} is not given, the server shall also suggest a
580 protocol to use for signing.  The client may use this suggested protocol
581 on its own discretion.  The same status line as with PREP_ENCRYPT is
582 used for this.
583 @end deffn
584
585 @noindent 
586 To allow the UI-server to visually identify a running operation or to
587 associate operations the server MAY support the command:
588
589 @deffn Command SESSION @var{number} [@var{string}]
590 The @var{number} is an arbitrary value, a server may use to associate
591 simultaneous running sessions.  It is a 32 bit unsigned integer with
592 @code{0} as a special value indicating that no session association shall
593 be done.
594
595 If @var{string} is given, the server may use this as the title of a
596 window or, in the case of an email operation, to extract the sender's
597 address. The string may contain spaces; thus no plus-escaping is used.
598
599 This command may be used at any time and overrides the effect of the
600 last command.  A @code{RESET} undoes the effect of this command.
601
602 @end deffn