Moved UI server protocol specs to the GPGME manual.
authorWerner Koch <wk@gnupg.org>
Wed, 4 Jun 2008 14:19:11 +0000 (14:19 +0000)
committerWerner Koch <wk@gnupg.org>
Wed, 4 Jun 2008 14:19:11 +0000 (14:19 +0000)
ChangeLog
doc/gpgol.texi

index fee4499..634f1fa 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-06-04  Werner Koch  <wk@g10code.com>
+
+       * doc/gpgol.texi (Assuan Protocol): Remove protocol specs.  They
+       are now part of the GPGME manual.
+
 2008-05-28  Werner Koch  <wk@g10code.com>
 
        * Release 0.10.14.
index 1fc83df..27debfe 100644 (file)
@@ -134,425 +134,15 @@ menu and enables a few extra menu items.
 @node Assuan Protocol
 @chapter Description of the UI Server Protocol
 
-This section describes the protocol used between @acronym{GpgOL} and the
-User Interface Server (UI server).  All cryptographic operations are
-done by this server and the server is responsible for all dialogs.  If a
-a server is not available, @acronym{GpgOL} can only use a very limited
-internal crypto server.
+All cryptographic operations are done by a server and the server is
+responsible for all dialogs.  If a a server is not available,
+@acronym{GpgOL} does not work.
 
-We assume that the connection has already been established; see the
-Assuan manual for details.
+This protocol used between @acronym{GpgOL} and the User Interface Server
+(UI server) is specified in the `GPGME Reference Manual', under the
+heading `The GnuPG UI Server Protocol'.
 
-@menu
-* ENCRYPT::                  Encrypt a message.
-* SIGN::                     Sign a message.
-* DECRYPT::                  Decrypt a message.
-* VERIFY::                   Verify a message.
-* Miscellaneous Commands::   Commands not related to a specific operation.
-@end menu
-
-
-
-@node ENCRYPT
-@section Encrypt a Message
-
-Before encryption can be done the recipients must be set using the
-command:
-
-@deffn Command RECIPIENT @var{string}
-
-Set the recipient for the encryption.  @var{string} is an RFC-2822
-recipient name ("mailbox" as per section 3.4).  This command may or may
-not check the recipient for validity right away; if it does not all
-recipients are expected to be checked at the time of the @code{ENCRYPT}
-command.  All @code{RECIPIENT} commands are cumulative until a
-successful @code{ENCRYPT} command or until a @code{RESET} command.
-Linefeeds are obviously not allowed in @var{string} and should be folded
-into spaces (which are equivalent).
-@end deffn
-
-@noindent
-To tell the server the source and destination of the data, the next two
-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. 
-
-GpgOL is a Windows only program, thus @var{n} is not a libc file
-descriptor but a regular system handle.  Given that the Assuan
-connection works over a socket, it is not possible to use regular
-inheritance to make the file descriptor available to the server.
-Thus @code{DuplicateHandle} needs to be used to duplicate a handle
-to the server process.  This is the reason that the server needs to
-implement the @code{GETINFO pid} command.  Sending this command a second
-time replaces the file descriptor set by the last one.
-@c If @var{n} is not given, this commands uses the
-@c %last file descriptor passed to the application.
-@c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
-@c %Libassuan manual}, on how to do descriptor passing.
-@end deffn
-
-@deffn Command OUTPUT FD=@var{n}
-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.
-@end deffn
-
-@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:
-
-@deffn Command ENCRYPT -@w{}-protocol=@var{name}
-
-This command reads the plaintext from the file descriptor set by the
-@code{INPUT} command, encrypts it and writes the ciphertext to the file
-descriptor set by the @code{OUTPUT} command.  The server may (and
-should) overlap reading and writing.  The recipients used for the
-encryption are all the recipients set so far.  If any recipient is not
-usable the server should take appropriate measures to notify the user
-about the problem and may cancel the operation by returning an error
-code.  The used file descriptors are void after this command; the
-recipient list is only cleared if the server returns success.
-
-@noindent
-Because GpgOL uses a streaming mode of operation the server is not
-allowed to auto select the protocol and must obey to the mandatory
-@var{protocol} parameter:
-
-@table @code
-@item OpenPGP
-Use the OpenPGP protocol (RFC-2440).
-@item CMS
-Use the CMS (PKCS#7) protocol (RFC-3852).
-@end table
-
-@end deffn
-
-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}]
-
-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
-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}
-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 this command is given again before a successful @command{ENCRYPT}
-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
-selected by the user) by means of a status line:
-@end deffn
-
-@deffn {Status line} PROTOCOL @var{name}
-Advise the client to use the protocol @var{name} for the
-@command{ENCRYPT} command.  The valid protocol names are listed under
-the description of the @command{ENCRYPT} command.  The server shall emit
-exactly one PROTOCOL status line.
-@end deffn
-
-@noindent
-Here is an example of a complete encryption sequence; client lines are
-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
-@end group
-@end smallexample
-
-
-
-@node SIGN
-@section Sign a Message
-
-The server needs to implement opaque signing as well as detached
-signing.  Due to the nature of OpenPGP messages it is always required to
-send the entire message to the server; sending just the hash is not
-possible.  The following two commands are required to set the input and
-output file descriptors:
-
-@deffn Command INPUT FD=@var{n}
-Set the file descriptor for the message to be signed to @var{n}.  The
-message send to the server is binary encoded.  For details on the file
-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.
-@end deffn
-
-@noindent
-To allow the server the selection of a non-default signing key the
-client may optionally use the @code{SENDER} command, see @ref{command
-SENDER}.
-
-@noindent
-The signing operation is then initiated by:
-
-@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
-@code{ENCRYPT} command.  With option @code{--detached} given, a detached
-signature is created; this is actually the usual way the command is
-used.
-@end deffn
-
-@noindent
-The client expects the server to send at least this status information
-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
-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
-prefixed with "@code{pgp-}".
-@end deffn
-
-
-
-@node DECRYPT
-@section Decrypt a Message
-
-Decryption may include the verification of OpenPGP messages.  This is
-due to the often used combined signing/encryption modus of OpenPGP.  The
-client may pass an option to the server to inhibit the signature
-verification.  The following two commands are required to set the input
-and output file descriptors:
-
-@deffn Command INPUT FD=@var{n}
-Set the file descriptor for the message to be decrypted to @var{n}.  The
-message send to the server is either binary encoded or --- in the case
-of OpenPGP --- ASCII armored.  For details on the file 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 binary
-encoded. For details on the file descriptor, see the description of
-@code{INPUT} in the @code{ENCRYPT} section.
-@end deffn
-
-@noindent
-The decryption is started with the command:
-
-@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify]
-@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.
-@end deffn
-
-
-@node VERIFY
-@section Verify a 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. 
-
-@deffn Command MESSAGE FD=@var{n}
-This command is used with detached signatures to set the file descriptor
-for the signed data to @var{n}. The data is binary encoded (used
-verbatim).  For details on the file descriptor, see the description of
-@code{INPUT} in the @code{ENCRYPT} section.
-@end deffn
-
-@deffn Command INPUT FD=@var{n}
-Set the file descriptor for the opaque message or the signature part of
-a detached signature to @var{n}.  The message send to the server is
-either binary encoded or -- in the case of OpenPGP -- ASCII armored.
-For details on the file 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 binary
-encoded and only used for opaque signatures.  For details on the file
-descriptor, see the description of @code{INPUT} in the @code{ENCRYPT}
-section.
-@end deffn
 
-@noindent
-The verification is then started using:
-
-@deffn Command VERIFY -@w{}-protocol=@var{name} [-@w{}-silent]
-@var{name} is the signing protocol used for the message. For a
-description of the allowed protocols see the @code{ENCRYPT} command.
-This argument is mandatory.  Depending on the combination of
-@code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
-to select the appropriate verification mode:
-
-@table @asis
-@item MESSAGE and INPUT
-This indicates a detached signature.  Output data is not applicable.
-@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
-This indicates an opaque signature.  The server shall write the signed
-data to the file descriptor set by the output command.  This data shall
-even be written if the signatures can't be verified.
-@end table
-@end deffn
-
-With @option{--silent} the server shall not display any dialog; this is
-for example used by the client to get the content of opaque signed
-messages. The client expects the server to send at least this status
-information before the final OK response:
-
-@deffn {Status line} SIGSTATUS @var{flag} @var{displaystring}
-Returns the status for the signature and a short string explaining the
-status.  Valid values for @var{flag} are:
-
-@table @code
-@item none
-The message has a signature but it could not not be verified due to a
-missing key.
-@item green
-The signature is fully valid.
-@item yellow
-The signature is valid but additional information was shown regarding the
-validity of the key.
-@item red
-The signature is not valid. 
-@end table
-
-@var{displaystring} is a percent-and-plus-encoded string with a short
-human readable description of the status.  For example
-
-@smallexample
-S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
-@end smallexample
-
-Note that this string needs to fit into an Assuan line and should be
-short enough to be displayed as short one-liner on the clients window.
-As usual the encoding of this string is UTF-8 and it should be send in
-its translated form.
-
-The server shall send one status line for every signature found on the
-message.
-
-
-@end deffn
-
-
-
-@c
-@c M I S C E L L A N E O U S  C O M M A N D S
-@c
-@node Miscellaneous Commands
-@section Miscellaneous Commands
-
-The server needs to implement the following commands which are not
-related to a specific command:
-
-@deffn Command GETINFO @var{what}
-This is a multi purpose command, commonly used to return a variety of
-information.  The required subcommands as described by the @var{what}
-parameter are:
-
-@table @code
-@item pid
-Return the process id of the server in decimal notation using an Assuan
-data line.
-@end table
-@end deffn
-
-
-@noindent
-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} 
-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
-given as a hexadecimal value so that it is easier to convey pointer
-values (e.g. @code{HWND}).
-@end deffn
-
-
-@noindent
-GpgOL features a button to invoke the certificate manager.  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
-certificate manager).  The client expects that the key manager is brought
-into the foregound and that this command immediatley returns (does not
-wait until the key manager 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}
-@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
-@code{RESET} command.  A second command overrides the effect of the
-first one; if @var{email} is not given and @option{--info} is not used,
-the server shall use the default signing key.
-
-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.
-@end deffn
-
-@noindent 
-To allow the UI-server to visually identify a running operation or to
-associate operations the server MAY support the command:
-
-@deffn Command SESSION @var{number} [@var{string}]
-The @var{number} is an arbitrary value, a server may use to associate
-simultaneous running sessions.  It is a 32 bit unsigned integer with
-@code{0} as a special value indicating that no session association shall
-be done.
-
-If @var{string} is given, the server may use this as the title of a
-window or, in the case of an email operation, to extract the sender's
-address. The string may contain spaces; thus no plus-escaping is used.
-
-This command may be used at any time and overrides the effect of the
-last command.  A @code{RESET} undoes the effect of this command.
-
-@end deffn
 
 @c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 @c