Generate the ChangeLog from commit logs.
[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}] [-@w{}-expect-sign]
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 @option{--expect-sign} is given the server should expect that the
133 message will also be signed and use this hint to present a unified
134 recipient and signer selection dialog if possible and desired.  A
135 selected signer should then be cached for the expected SIGN command
136 (which is expected in the same session but possible on another
137 connection).
138
139 If this command is given again before a successful @command{ENCRYPT}
140 command, the second one takes effect.
141
142 Before sending the OK response the server shall tell the client the
143 protocol to be used (either the one given by the argument or the one
144 selected by the user) by means of a status line:
145 @end deffn
146
147 @deffn {Status line} PROTOCOL @var{name}
148 Advise the client to use the protocol @var{name} for the
149 @command{ENCRYPT} command.  The valid protocol names are listed under
150 the description of the @command{ENCRYPT} command.  The server shall emit
151 exactly one PROTOCOL status line.
152 @end deffn
153
154 @noindent
155 Here is an example of a complete encryption sequence; client lines are
156 indicated by a @sc{c:}, server responses by @sc{c:}:
157
158 @smallexample
159 @group
160   @clnt RESET
161   @srvr OK
162   @clnt RECIPIENT foo@@example.net
163   @srvr OK
164   @clnt RECIPIENT bar@@example.com
165   @srvr OK
166   @clnt PREP_ENCRYPT
167   @srvr S PROTOCOL OpenPGP
168   @srvr OK
169   @clnt INPUT FD=17
170   @srvr OK
171   @clnt OUTPUT FD=18
172   @srvr OK
173   @clnt ENCRYPT
174   @srvr OK
175 @end group
176 @end smallexample
177
178
179
180 @node UI Server Sign
181 @section UI Server: Sign a Message
182
183 The server needs to implement opaque signing as well as detached
184 signing.  Due to the nature of OpenPGP messages it is always required to
185 send the entire message to the server; sending just the hash is not
186 possible.  The following two commands are required to set the input and
187 output file descriptors:
188
189 @deffn Command INPUT FD=@var{n}
190 Set the file descriptor for the message to be signed to @var{n}.  The
191 message send to the server is binary encoded.  For details on the file
192 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
193 section.
194 @end deffn
195
196 @deffn Command OUTPUT FD=@var{n}
197 Set the file descriptor to be used for the output.  The output is either
198 the complete signed message or in case of a detached signature just that
199 detached signature.  For OpenPGP, the output needs to be ASCII armored;
200 for CMS, the output needs to be Base-64 encoded.  For details on the
201 file descriptor, see the @code{INPUT} command.
202 @end deffn
203
204 @noindent
205 To allow the server the selection of a non-default signing key the
206 client may optionally use the @code{SENDER} command, see @ref{command
207 SENDER}.
208
209 @noindent
210 The signing operation is then initiated by:
211
212 @deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] 
213 Sign the data set with the @code{INPUT} command and write it to the sink
214 set by OUTPUT.  @var{name} is the signing protocol used for the
215 message. For a description of the allowed protocols see the
216 @code{ENCRYPT} command.  With option @code{--detached} given, a detached
217 signature is created; this is actually the usual way the command is
218 used.
219 @end deffn
220
221 @noindent
222 The client expects the server to send at least this status information
223 before the final OK response:
224
225 @deffn {Status line} MICALG @var{string}
226 The @var{string} represents the hash algorithm used to create the
227 signature. It is used with MOSS style signature messages and defined by
228 PGP/MIME (RFC-3156) and S/MIME (RFC-3851).  The GPGME library has a
229 supporting function @code{gpgme_hash_algo_name} to return the algorithm
230 name as a string.  This string needs to be lowercased and for OpenPGP
231 prefixed with "@code{pgp-}".
232 @end deffn
233
234
235
236 @node UI Server Decrypt
237 @section UI Server: Decrypt a Message
238
239 Decryption may include the verification of OpenPGP messages.  This is
240 due to the often used combined signing/encryption modus of OpenPGP.  The
241 client may pass an option to the server to inhibit the signature
242 verification.  The following two commands are required to set the input
243 and output file descriptors:
244
245 @deffn Command INPUT FD=@var{n}
246 Set the file descriptor for the message to be decrypted to @var{n}.  The
247 message send to the server is either binary encoded or --- in the case
248 of OpenPGP --- ASCII armored.  For details on the file descriptor, see
249 the description of @code{INPUT} in the @code{ENCRYPT} section.
250 @end deffn
251
252 @deffn Command OUTPUT FD=@var{n}
253 Set the file descriptor to be used for the output. The output is binary
254 encoded. For details on the file descriptor, see the description of
255 @code{INPUT} in the @code{ENCRYPT} section.
256 @end deffn
257
258 @noindent
259 The decryption is started with the command:
260
261 @deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
262 @var{name} is the encryption protocol used for the message. For a
263 description of the allowed protocols see the @code{ENCRYPT} command.
264 This argument is mandatory.  If the option @option{--no-verify} is given,
265 the server should not try to verify a signature, in case the input data
266 is an OpenPGP combined message.
267 @end deffn
268
269
270 @node UI Server Verify
271 @section UI Server: Verify a Message
272
273 The server needs to support the verification of opaque signatures as
274 well as detached signatures.  The kind of input sources controls what
275 kind message is to be verified. 
276
277 @deffn Command MESSAGE FD=@var{n}
278 This command is used with detached signatures to set the file descriptor
279 for the signed data to @var{n}. The data is binary encoded (used
280 verbatim).  For details on the file descriptor, see the description of
281 @code{INPUT} in the @code{ENCRYPT} section.
282 @end deffn
283
284 @deffn Command INPUT FD=@var{n}
285 Set the file descriptor for the opaque message or the signature part of
286 a detached signature to @var{n}.  The message send to the server is
287 either binary encoded or -- in the case of OpenPGP -- ASCII armored.
288 For details on the file descriptor, see the description of @code{INPUT}
289 in the @code{ENCRYPT} 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 binary
294 encoded and only used for opaque signatures.  For details on the file
295 descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
296 section.
297 @end deffn
298
299 @noindent
300 The verification is then started using:
301
302 @deffn Command VERIFY -@w{}-protocol=@var{name} [-@w{}-silent]
303 @var{name} is the signing protocol used for the message. For a
304 description of the allowed protocols see the @code{ENCRYPT} command.
305 This argument is mandatory.  Depending on the combination of
306 @code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
307 to select the appropriate verification mode:
308
309 @table @asis
310 @item MESSAGE and INPUT
311 This indicates a detached signature.  Output data is not applicable.
312 @item INPUT 
313 This indicates an opaque signature.  As no output command has been given,
314 the server is only required to check the signature.
315 @item INPUT and OUTPUT
316 This indicates an opaque signature.  The server shall write the signed
317 data to the file descriptor set by the output command.  This data shall
318 even be written if the signatures can't be verified.
319 @end table
320 @end deffn
321
322 With @option{--silent} the server shall not display any dialog; this is
323 for example used by the client to get the content of opaque signed
324 messages. The client expects the server to send at least this status
325 information before the final OK response:
326
327 @deffn {Status line} SIGSTATUS @var{flag} @var{displaystring}
328 Returns the status for the signature and a short string explaining the
329 status.  Valid values for @var{flag} are:
330
331 @table @code
332 @item none
333 The message has a signature but it could not not be verified due to a
334 missing key.
335 @item green
336 The signature is fully valid.
337 @item yellow
338 The signature is valid but additional information was shown regarding the
339 validity of the key.
340 @item red
341 The signature is not valid. 
342 @end table
343
344 @var{displaystring} is a percent-and-plus-encoded string with a short
345 human readable description of the status.  For example
346
347 @smallexample
348 S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
349 @end smallexample
350
351 Note that this string needs to fit into an Assuan line and should be
352 short enough to be displayed as short one-liner on the clients window.
353 As usual the encoding of this string is UTF-8 and it should be send in
354 its translated form.
355
356 The server shall send one status line for every signature found on the
357 message.
358
359
360 @end deffn
361
362
363 @node UI Server Set Input Files
364 @section UI Server: Specifying the input files to operate on.
365
366 All file related UI server commands operate on a number of input files
367 or directories, specified by one or more @code{FILE} commands:
368
369 @deffn Command FILE @var{name} [--continued]
370 Add the file or directory @var{name} to the list of pathnames to be
371 processed by the server.  The parameter @var{name} must be an absolute
372 path name (including the drive letter) and is percent espaced (in
373 particular, the characters %, = and white space characters are always
374 escaped).  The option @code{--continued} is present for all but the
375 last @code{FILE} command.
376 @end deffn
377
378
379 @node UI Server Sign/Encrypt Files
380 @section UI Server: Encrypting and signing files.
381
382 First, the input files need to be specified by one or more
383 @code{FILE} commands.  Afterwards, the actual operation is requested:
384
385 @deffn Command ENCRYPT_FILES --nohup
386 @deffnx Command SIGN_FILES --nohup
387 @deffnx Command ENCRYPT_SIGN_FILES --nohup
388 Request that the files specified by @code{FILE} are encrypted and/or
389 signed.  The command selects the default action.  The UI server may
390 allow the user to change this default afterwards interactively, and
391 even abort the operation or complete it only on some of the selected
392 files and directories.
393
394 What it means to encrypt or sign a file or directory is specific to
395 the preferences of the user, the functionality the UI server provides,
396 and the selected protocol.  Typically, for each input file a new file
397 is created under the original filename plus a protocol specific
398 extension (like @code{.gpg} or @code{.sig}), which contain the
399 encrypted/signed file or a detached signature.  For directories, the
400 server may offer multiple options to the user (for example ignore or
401 process recursively).
402
403 The @code{ENCRYPT_SIGN_FILES} command requests a combined sign and
404 encrypt operation.  It may not be available for all protocols (for
405 example, it is available for OpenPGP but not for CMS).
406
407 The option @code{--nohup} is mandatory.  It is currently unspecified
408 what should happen if @code{--nohup} is not present.  Because
409 @code{--nohup} is present, the server always returns @code{OK}
410 promptly, and completes the operation asynchronously.
411 @end deffn
412
413
414 @node UI Server Verify/Decrypt Files
415 @section UI Server: Decrypting and verifying files.
416
417 First, the input files need to be specified by one or more
418 @code{FILE} commands.  Afterwards, the actual operation is requested:
419
420 @deffn Command DECRYPT_FILES --nohup
421 @deffnx Command VERIFY_FILES --nohup
422 @deffnx Command DECRYPT_VERIFY_FILES --nohup
423 Request that the files specified by @code{FILE} are decrypted and/or
424 verified.  The command selects the default action.  The UI server may
425 allow the user to change this default afterwards interactively, and
426 even abort the operation or complete it only on some of the selected
427 files and directories.
428
429 What it means to decrypt or verify a file or directory is specific to
430 the preferences of the user, the functionality the UI server provides,
431 and the selected protocol.  Typically, for decryption, a new file is
432 created for each input file under the original filename minus a
433 protocol specific extension (like @code{.gpg}) which contains the
434 original plaintext.  For verification a status is displayed for each
435 signed input file, indicating if it is signed, and if yes, if the
436 signature is valid.  For files that are signed and encrypted, the
437 @code{VERIFY} command transiently decrypts the file to verify the
438 enclosed signature.  For directories, the server may offer multiple
439 options to the user (for example ignore or process recursively).
440
441 The option @code{--nohup} is mandatory.  It is currently unspecified
442 what should happen if @code{--nohup} is not present.  Because
443 @code{--nohup} is present, the server always returns @code{OK}
444 promptly, and completes the operation asynchronously.
445 @end deffn
446
447
448 @node UI Server Import/Export Keys
449 @section UI Server: Managing certificates.
450
451 First, the input files need to be specified by one or more
452 @code{FILE} commands.  Afterwards, the actual operation is requested:
453
454 @deffn Command IMPORT_FILES --nohup
455 Request that the certificates contained in the files specified by
456 @code{FILE} are imported into the local certificate databases.
457
458 For directories, the server may offer multiple options to the user
459 (for example ignore or process recursively).
460
461 The option @code{--nohup} is mandatory.  It is currently unspecified
462 what should happen if @code{--nohup} is not present.  Because
463 @code{--nohup} is present, the server always returns @code{OK}
464 promptly, and completes the operation asynchronously.
465 @end deffn
466
467 FIXME: It may be nice to support an @code{EXPORT} command as well,
468 which is enabled by the context menu of the background of a directory.
469
470
471 @node UI Server Checksum Files
472 @section UI Server: Create and verify checksums for files.
473
474 First, the input files need to be specified by one or more
475 @code{FILE} commands.  Afterwards, the actual operation is requested:
476
477 @deffn Command CHECKSUM_CREATE_FILES --nohup
478 Request that checksums are created for the files specifed by
479 @code{FILE}.  The choice of checksum algorithm and the destination
480 storage and format for the created checksums depend on the preferences
481 of the user and the functionality provided by the UI server.  For
482 directories, the server may offer multiple options to the user (for
483 example ignore or process recursively).
484
485 The option @code{--nohup} is mandatory.  It is currently unspecified
486 what should happen if @code{--nohup} is not present.  Because
487 @code{--nohup} is present, the server always returns @code{OK}
488 promptly, and completes the operation asynchronously.
489 @end deffn
490
491
492 @deffn Command CHECKSUM_VERIFY_FILES --nohup
493 Request that checksums are created for the files specifed by
494 @code{FILE} and verified against previously created and stored
495 checksums.  The choice of checksum algorithm and the source storage
496 and format for previously created checksums depend on the preferences
497 of the user and the functionality provided by the UI server.  For
498 directories, the server may offer multiple options to the user (for
499 example ignore or process recursively).
500
501 If the source storage of previously created checksums is available to
502 the user through the Windows shell, this command may also accept such
503 checksum files as @code{FILE} arguments.  In this case, the UI server
504 should instead verify the checksum of the referenced files as if they
505 were given as INPUT files.
506
507 The option @code{--nohup} is mandatory.  It is currently unspecified
508 what should happen if @code{--nohup} is not present.  Because
509 @code{--nohup} is present, the server always returns @code{OK}
510 promptly, and completes the operation asynchronously.
511 @end deffn
512
513
514
515
516 @c
517 @c M I S C E L L A N E O U S  C O M M A N D S
518 @c
519 @node Miscellaneous UI Server Commands
520 @section Miscellaneous UI Server Commands
521
522 The server needs to implement the following commands which are not
523 related to a specific command:
524
525 @deffn Command GETINFO @var{what}
526 This is a multi purpose command, commonly used to return a variety of
527 information.  The required subcommands as described by the @var{what}
528 parameter are:
529
530 @table @code
531 @item pid
532 Return the process id of the server in decimal notation using an Assuan
533 data line.
534 @end table
535 @end deffn
536
537
538 @noindent
539 To allow the server to pop up the windows in the correct relation to the
540 client, the client is advised to tell the server by sending the option:
541
542 @deffn {Command option} window-id @var{number} 
543 The @var{number} represents the native window ID of the clients current
544 window.  On Windows systems this is a windows handle (@code{HWND}) and
545 on X11 systems it is the @code{X Window ID}.  The number needs to be
546 given as a hexadecimal value so that it is easier to convey pointer
547 values (e.g. @code{HWND}).
548 @end deffn
549
550
551 @noindent
552 A client may want to fire up the certificate manager of the server.  To
553 do this it uses the Assuan command:
554
555 @deffn Command START_KEYMANAGER
556 The server shall pop up the main window of the key manager (aka
557 certificate manager).  The client expects that the key manager is brought
558 into the foregound and that this command immediatley returns (does not
559 wait until the key manager has been fully brought up).
560 @end deffn
561
562 @noindent
563 A client may want to fire up the configuration dialog of the server.  To
564 do this it uses the Assuan command:
565
566 @deffn Command START_CONFDIALOG
567 The server shall pop up its configuration dialog.  The client expects
568 that this dialog is brought into the foregound and that this command
569 immediatley returns (i.e. it does not wait until the dialog has been
570 fully brought up).
571 @end deffn
572
573 @anchor{command SENDER}
574 @noindent
575 When doing an operation on a mail, it is useful to let the server know
576 the address of the sender:
577
578 @deffn Command SENDER [-@w{}-info] [-@w{}-protocol=@var{name}] @var{email}
579 @var{email} is the plain ASCII encoded address ("addr-spec" as per
580 RFC-2822) enclosed in angle brackets.  The address set with this command
581 is valid until a successful completion of the operation or until a
582 @code{RESET} command.  A second command overrides the effect of the
583 first one; if @var{email} is not given and @option{--info} is not used,
584 the server shall use the default signing key.
585
586 If option @option{--info} is not given, the server shall also suggest a
587 protocol to use for signing.  The client may use this suggested protocol
588 on its own discretion.  The same status line as with PREP_ENCRYPT is
589 used for this.
590
591 The option @option{--protocol} may be used to give the server a hint on
592 which signing protocol should be preferred.
593 @end deffn
594
595 @noindent 
596 To allow the UI-server to visually identify a running operation or to
597 associate operations the server MAY support the command:
598
599 @deffn Command SESSION @var{number} [@var{string}]
600 The @var{number} is an arbitrary value, a server may use to associate
601 simultaneous running sessions.  It is a 32 bit unsigned integer with
602 @code{0} as a special value indicating that no session association shall
603 be done.
604
605 If @var{string} is given, the server may use this as the title of a
606 window or, in the case of an email operation, to extract the sender's
607 address. The string may contain spaces; thus no plus-escaping is used.
608
609 This command may be used at any time and overrides the effect of the
610 last command.  A @code{RESET} undoes the effect of this command.
611
612 @end deffn