[svn] GpgOL - r255 - in trunk: . doc
svn author wk
cvs at cvs.gnupg.org
Wed Jun 4 16:19:12 CEST 2008
Author: wk
Date: 2008-06-04 16:19:11 +0200 (Wed, 04 Jun 2008)
New Revision: 255
Modified:
trunk/ChangeLog
trunk/doc/gpgol.texi
Log:
Moved UI server protocol specs to the GPGME manual.
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2008-05-28 14:08:03 UTC (rev 254)
+++ trunk/ChangeLog 2008-06-04 14:19:11 UTC (rev 255)
@@ -1,3 +1,8 @@
+2008-06-04 Werner Koch <wk at g10code.com>
+
+ * doc/gpgol.texi (Assuan Protocol): Remove protocol specs. They
+ are now part of the GPGME manual.
+
2008-05-28 Werner Koch <wk at g10code.com>
* Release 0.10.14.
Modified: trunk/doc/gpgol.texi
===================================================================
--- trunk/doc/gpgol.texi 2008-05-28 14:08:03 UTC (rev 254)
+++ trunk/doc/gpgol.texi 2008-06-04 14:19:11 UTC (rev 255)
@@ -134,426 +134,16 @@
@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,
+ at 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'.
- at 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.
- at end menu
-
- at node ENCRYPT
- at section Encrypt a Message
-
-Before encryption can be done the recipients must be set using the
-command:
-
- at 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).
- at end deffn
-
- at noindent
-To tell the server the source and destination of the data, the next two
-commands are to be used:
-
- at 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.
- at c If @var{n} is not given, this commands uses the
- at c %last file descriptor passed to the application.
- at c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
- at c %Libassuan manual}, on how to do descriptor passing.
- at end deffn
-
- at 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.
- at end deffn
-
- at 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:
-
- at deffn Command ENCRYPT - at w{}-protocol=@var{name}
-
-This command reads the plaintext from the file descriptor set by the
- at 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.
-
- at 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
- at var{protocol} parameter:
-
- at table @code
- at item OpenPGP
-Use the OpenPGP protocol (RFC-2440).
- at item CMS
-Use the CMS (PKCS#7) protocol (RFC-3852).
- at end table
-
- at end deffn
-
-To support automagically selection of the protocol depending on the
-selected keys, the server MAY implement the command:
-
- at deffn Command PREP_ENCRYPT [- at 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:
- at end deffn
-
- at deffn {Status line} PROTOCOL @var{name}
-Advise the client to use the protocol @var{name} for the
- at 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.
- at end deffn
-
- at noindent
-Here is an example of a complete encryption sequence; client lines are
-indicated by a @sc{c:}, server responses by @sc{c:}:
-
- at smallexample
- at 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
- at end group
- at end smallexample
-
-
-
- at node SIGN
- at 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:
-
- at 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.
- at end deffn
-
- at 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.
- at end deffn
-
- at 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}.
-
- at noindent
-The signing operation is then initiated by:
-
- at deffn Command SIGN - at w{}-protocol=@var{name} [- at 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
- at code{ENCRYPT} command. With option @code{--detached} given, a detached
-signature is created; this is actually the usual way the command is
-used.
- at end deffn
-
- at noindent
-The client expects the server to send at least this status information
-before the final OK response:
-
- at 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-}".
- at end deffn
-
-
-
- at node DECRYPT
- at 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:
-
- at 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.
- at end deffn
-
- at 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
- at code{INPUT} in the @code{ENCRYPT} section.
- at end deffn
-
- at noindent
-The decryption is started with the command:
-
- at deffn Command DECRYPT - at w{}-protocol=@var{name} [- at w{}-no-verify]
- at 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.
- at end deffn
-
-
- at node VERIFY
- at 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.
-
- at 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
- at code{INPUT} in the @code{ENCRYPT} section.
- at end deffn
-
- at 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.
- at end deffn
-
- at 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.
- at end deffn
-
- at noindent
-The verification is then started using:
-
- at deffn Command VERIFY - at w{}-protocol=@var{name} [- at w{}-silent]
- at 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
- at code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs
-to select the appropriate verification mode:
-
- at table @asis
- at item MESSAGE and INPUT
-This indicates a detached signature. Output data is not applicable.
- at item INPUT
-This indicates an opaque signature. As no output command has been given,
-the server is only required to check the signature.
- at 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.
- at end table
- at 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:
-
- at 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:
-
- at table @code
- at item none
-The message has a signature but it could not not be verified due to a
-missing key.
- at item green
-The signature is fully valid.
- at item yellow
-The signature is valid but additional information was shown regarding the
-validity of the key.
- at item red
-The signature is not valid.
- at end table
-
- at var{displaystring} is a percent-and-plus-encoded string with a short
-human readable description of the status. For example
-
- at smallexample
-S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net>
- at 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.
-
-
- at end deffn
-
-
-
- at c
- at c M I S C E L L A N E O U S C O M M A N D S
- at c
- at node Miscellaneous Commands
- at section Miscellaneous Commands
-
-The server needs to implement the following commands which are not
-related to a specific command:
-
- at 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:
-
- at table @code
- at item pid
-Return the process id of the server in decimal notation using an Assuan
-data line.
- at end table
- at end deffn
-
-
- at 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:
-
- at 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}).
- at end deffn
-
-
- at noindent
-GpgOL features a button to invoke the certificate manager. To do this
-it uses the Assuan command:
-
- at 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).
- at end deffn
-
- at anchor{command SENDER}
- at noindent
-When doing an operation on a mail, it is useful to let the server know
-the address of the sender:
-
- at deffn Command SENDER [- at w{}-info] @var{email}
- at 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
- at 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.
- at end deffn
-
- at noindent
-To allow the UI-server to visually identify a running operation or to
-associate operations the server MAY support the command:
-
- at 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
- at 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.
-
- at end deffn
-
@c xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@c
@c M A P I P r o p e r t i e s
More information about the Gnupg-commits
mailing list