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