docs: cython sanitized
[gpgme.git] / doc / uiserver.texi
index c372750..6938aee 100644 (file)
@@ -61,7 +61,7 @@ commands are to be used:
 
 @deffn Command INPUT FD=@var{n}
 Set the file descriptor for the message to be encrypted to @var{n}.  The
-message send to the server is binary encoded. 
+message send to the server is binary encoded.
 
 GpgOL is a Windows only program, thus @var{n} is not a libc file
 descriptor but a regular system handle.  Given that the Assuan
@@ -77,14 +77,15 @@ time replaces the file descriptor set by the last one.
 @c %Libassuan manual}, on how to do descriptor passing.
 @end deffn
 
-@deffn Command OUTPUT FD=@var{n}
+@deffn Command OUTPUT FD=@var{n} [--binary]
 Set the file descriptor to be used for the output (i.e. the encrypted
-message) to @var{n}.  For OpenPGP, the output needs to be ASCII armored;
-for CMS, the output needs to be Base-64 encoded.  For details on the
-file descriptor, see the @code{INPUT} command.
+message) to @var{n}.  If the option @code{--binary} is given the
+output shall be in binary format; if not given, the output for OpenPGP
+needs to be ASCII armored and for CMS Base-64 encoded.  For details on
+the file descriptor, see the @code{INPUT} command.
 @end deffn
 
-@noindent  
+@noindent
 The setting of the recipients, the data source and destination may
 happen in any order, even intermixed.  If this has been done the actual
 encryption operation is called using:
@@ -118,10 +119,10 @@ Use the CMS (PKCS#7) protocol (RFC-3852).
 To support automagically selection of the protocol depending on the
 selected keys, the server MAY implement the command:
 
-@deffn Command PREP_ENCRYPT [-@w{}-protocol=@var{name}]
+@deffn Command PREP_ENCRYPT [-@w{}-protocol=@var{name}] [-@w{}-expect-sign]
 
 This commands considers all recipients set so far and decides whether it
-is able to take input and start the actual decryption.  This is kind of
+is able to take input and start the actual encryption.  This is kind of
 a dry-run @command{ENCRYPT} without requiring or using the input and
 output file descriptors.  The server shall cache the result of any user
 selection to avoid asking this again when the actual @command{ENCRYPT}
@@ -129,8 +130,15 @@ command is send.  The @option{--protocol} option is optional; if it is
 not given, the server should allow the user to select the protocol to be
 used based on the recipients given or by any other means.
 
+If @option{--expect-sign} is given the server should expect that the
+message will also be signed and use this hint to present a unified
+recipient and signer selection dialog if possible and desired.  A
+selected signer should then be cached for the expected SIGN command
+(which is expected in the same session but possible on another
+connection).
+
 If this command is given again before a successful @command{ENCRYPT}
-command, the second one takes effect. 
+command, the second one takes effect.
 
 Before sending the OK response the server shall tell the client the
 protocol to be used (either the one given by the argument or the one
@@ -150,21 +158,21 @@ indicated by a @sc{c:}, server responses by @sc{c:}:
 
 @smallexample
 @group
-  @clnt RESET
-  @srvr OK
-  @clnt RECIPIENT foo@@example.net
-  @srvr OK
-  @clnt RECIPIENT bar@@example.com
-  @srvr OK
-  @clnt PREP_ENCRYPT
-  @srvr S PROTOCOL OpenPGP
-  @srvr OK
-  @clnt INPUT FD=17
-  @srvr OK
-  @clnt OUTPUT FD=18
-  @srvr OK
-  @clnt ENCRYPT
-  @srvr OK
+  @clnt{RESET}
+  @srvr{OK}
+  @clnt{RECIPIENT foo@@example.net}
+  @srvr{OK}
+  @clnt{RECIPIENT bar@@example.com}
+  @srvr{OK}
+  @clnt{PREP_ENCRYPT}
+  @srvr{S PROTOCOL OpenPGP}
+  @srvr{OK}
+  @clnt{INPUT FD=17}
+  @srvr{OK}
+  @clnt{OUTPUT FD=18}
+  @srvr{OK}
+  @clnt{ENCRYPT}
+  @srvr{OK}
 @end group
 @end smallexample
 
@@ -186,12 +194,13 @@ descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
 section.
 @end deffn
 
-@deffn Command OUTPUT FD=@var{n}
-Set the file descriptor to be used for the output.  The output is either
-the complete signed message or in case of a detached signature just that
-detached signature.  For OpenPGP, the output needs to be ASCII armored;
-for CMS, the output needs to be Base-64 encoded.  For details on the
-file descriptor, see the @code{INPUT} command.
+@deffn Command OUTPUT FD=@var{n} [--binary]
+Set the file descriptor to be used for the output.  The output is
+either the complete signed message or in case of a detached signature
+just that detached signature.  If the option @code{--binary} is given
+the output shall be in binary format; if not given, the output for
+OpenPGP needs to be ASCII armored and for CMS Base-64 encoded.  For
+details on the file descriptor, see the @code{INPUT} command.
 @end deffn
 
 @noindent
@@ -202,7 +211,7 @@ SENDER}.
 @noindent
 The signing operation is then initiated by:
 
-@deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] 
+@deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached]
 Sign the data set with the @code{INPUT} command and write it to the sink
 set by OUTPUT.  @var{name} is the signing protocol used for the
 message. For a description of the allowed protocols see the
@@ -217,7 +226,7 @@ before the final OK response:
 
 @deffn {Status line} MICALG @var{string}
 The @var{string} represents the hash algorithm used to create the
-signature. It is used with MOSS style signature messages and defined by
+signature. It is used with RFC-1847 style signature messages and defined by
 PGP/MIME (RFC-3156) and S/MIME (RFC-3851).  The GPGME library has a
 supporting function @code{gpgme_hash_algo_name} to return the algorithm
 name as a string.  This string needs to be lowercased and for OpenPGP
@@ -251,12 +260,14 @@ encoded. For details on the file descriptor, see the description of
 @noindent
 The decryption is started with the command:
 
-@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
+@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify] [-@w{}-export-session-key]
 @var{name} is the encryption protocol used for the message. For a
 description of the allowed protocols see the @code{ENCRYPT} command.
-This argument is mandatory.  If the option @option{--no-verify} is given,
-the server should not try to verify a signature, in case the input data
-is an OpenPGP combined message.
+This argument is mandatory.  If the option @option{--no-verify} is
+given, the server should not try to verify a signature, in case the
+input data is an OpenPGP combined message. If the option
+@option{--export-session-key} is given and the underlying engine knows
+how to export the session key, it will appear on a status line
 @end deffn
 
 
@@ -265,7 +276,7 @@ is an OpenPGP combined message.
 
 The server needs to support the verification of opaque signatures as
 well as detached signatures.  The kind of input sources controls what
-kind message is to be verified. 
+kind message is to be verified.
 
 @deffn Command MESSAGE FD=@var{n}
 This command is used with detached signatures to set the file descriptor
@@ -302,7 +313,7 @@ to select the appropriate verification mode:
 @table @asis
 @item MESSAGE and INPUT
 This indicates a detached signature.  Output data is not applicable.
-@item INPUT 
+@item INPUT
 This indicates an opaque signature.  As no output command has been given,
 the server is only required to check the signature.
 @item INPUT and OUTPUT
@@ -331,7 +342,7 @@ The signature is fully valid.
 The signature is valid but additional information was shown regarding the
 validity of the key.
 @item red
-The signature is not valid. 
+The signature is not valid.
 @end table
 
 @var{displaystring} is a percent-and-plus-encoded string with a short
@@ -359,13 +370,18 @@ message.
 All file related UI server commands operate on a number of input files
 or directories, specified by one or more @code{FILE} commands:
 
-@deffn Command FILE @var{name} [--continued]
+@deffn Command FILE [--clear] @var{name}
 Add the file or directory @var{name} to the list of pathnames to be
 processed by the server.  The parameter @var{name} must be an absolute
 path name (including the drive letter) and is percent espaced (in
 particular, the characters %, = and white space characters are always
-escaped).  The option @code{--continued} is present for all but the
-last @code{FILE} command.
+escaped).  If the option @code{--clear} is given, the list of files is
+cleared before adding @var{name}.
+
+Historical note: The original spec did not define @code{--clear} but
+the keyword @code{--continued} after the file name to indicate that
+more files are to be expected.  However, this has never been used and
+thus removed from the specs.
 @end deffn
 
 
@@ -468,7 +484,7 @@ First, the input files need to be specified by one or more
 @code{FILE} commands.  Afterwards, the actual operation is requested:
 
 @deffn Command CHECKSUM_CREATE_FILES --nohup
-Request that checksums are created for the files specifed by
+Request that checksums are created for the files specified by
 @code{FILE}.  The choice of checksum algorithm and the destination
 storage and format for the created checksums depend on the preferences
 of the user and the functionality provided by the UI server.  For
@@ -483,7 +499,7 @@ promptly, and completes the operation asynchronously.
 
 
 @deffn Command CHECKSUM_VERIFY_FILES --nohup
-Request that checksums are created for the files specifed by
+Request that checksums are created for the files specified by
 @code{FILE} and verified against previously created and stored
 checksums.  The choice of checksum algorithm and the source storage
 and format for previously created checksums depend on the preferences
@@ -532,7 +548,7 @@ data line.
 To allow the server to pop up the windows in the correct relation to the
 client, the client is advised to tell the server by sending the option:
 
-@deffn {Command option} window-id @var{number} 
+@deffn {Command option} window-id @var{number}
 The @var{number} represents the native window ID of the clients current
 window.  On Windows systems this is a windows handle (@code{HWND}) and
 on X11 systems it is the @code{X Window ID}.  The number needs to be
@@ -542,8 +558,8 @@ values (e.g. @code{HWND}).
 
 
 @noindent
-GpgOL features a button to invoke the certificate manager.  To do this
-it uses the Assuan command:
+A client may want to fire up the certificate manager of the server.  To
+do this it uses the Assuan command:
 
 @deffn Command START_KEYMANAGER
 The server shall pop up the main window of the key manager (aka
@@ -552,12 +568,23 @@ into the foregound and that this command immediatley returns (does not
 wait until the key manager has been fully brought up).
 @end deffn
 
+@noindent
+A client may want to fire up the configuration dialog of the server.  To
+do this it uses the Assuan command:
+
+@deffn Command START_CONFDIALOG
+The server shall pop up its configuration dialog.  The client expects
+that this dialog is brought into the foregound and that this command
+immediatley returns (i.e. it does not wait until the dialog has been
+fully brought up).
+@end deffn
+
 @anchor{command SENDER}
 @noindent
 When doing an operation on a mail, it is useful to let the server know
 the address of the sender:
 
-@deffn Command SENDER [-@w{}-info] @var{email}
+@deffn Command SENDER [-@w{}-info] [-@w{}-protocol=@var{name}] @var{email}
 @var{email} is the plain ASCII encoded address ("addr-spec" as per
 RFC-2822) enclosed in angle brackets.  The address set with this command
 is valid until a successful completion of the operation or until a
@@ -569,9 +596,12 @@ If option @option{--info} is not given, the server shall also suggest a
 protocol to use for signing.  The client may use this suggested protocol
 on its own discretion.  The same status line as with PREP_ENCRYPT is
 used for this.
+
+The option @option{--protocol} may be used to give the server a hint on
+which signing protocol should be preferred.
 @end deffn
 
-@noindent 
+@noindent
 To allow the UI-server to visually identify a running operation or to
 associate operations the server MAY support the command: