From 1b2ad3b73c37d0583b8e438b4707dca60e26ae7e Mon Sep 17 00:00:00 2001 From: Andre Heinecke Date: Tue, 12 Nov 2019 11:04:11 +0100 Subject: [PATCH] doc: Remove UI Server documentation * doc/Makefile.am: Remove uiserver.texi * doc/gpgme.texi: Remove UI-Server mentions. * doc/uiserver.texi: Removed. -- This prepares the removal of UI Server from implementing applications like Kleopatra. The only user of the UI Server is GpgEX and even that does not need it at all and is better served with process calls. GnuPG-Bug-Id: T4030 --- doc/Makefile.am | 2 +- doc/gpgme.texi | 17 -- doc/uiserver.texi | 621 ---------------------------------------------- 3 files changed, 1 insertion(+), 639 deletions(-) delete mode 100644 doc/uiserver.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index f722980f..3f783538 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -30,7 +30,7 @@ BUILT_SOURCES = defsincdate defs.inc info_TEXINFOS = gpgme.texi -gpgme_TEXINFOS = uiserver.texi lesser.texi gpl.texi +gpgme_TEXINFOS = lesser.texi gpl.texi gpgme.texi : defs.inc diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 36c2b32b..ffaf8b42 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -103,7 +103,6 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of Appendices -* UI Server Protocol:: The GnuPG UI Server Protocol. * Debugging:: How to solve problems. * Deprecated Functions:: Documentation of deprecated functions. @@ -902,9 +901,6 @@ This specifies the raw Assuan protocol. Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. -@item GPGME_PROTOCOL_UISERVER -Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. - @item GPGME_PROTOCOL_SPAWN @since{1.5.0} @@ -981,9 +977,6 @@ gpg-agent. @item dirmngr-socket Return the name of the socket to connect to the dirmngr. -@item uiserver-socket -Return the name of the socket to connect to the user interface server. - @item gpgconf-name Return the file name of the engine configuration tool. @@ -6254,14 +6247,6 @@ plaintext shall not be compressed before it is encrypted. This is in some cases useful if the length of the encrypted message may reveal information about the plaintext. -@item GPGME_ENCRYPT_PREPARE -@itemx GPGME_ENCRYPT_EXPECT_SIGN -The @code{GPGME_ENCRYPT_PREPARE} symbol is used with the UI Server -protocol to prepare an encryption (i.e. sending the -@code{PREP_ENCRYPT} command). With the -@code{GPGME_ENCRYPT_EXPECT_SIGN} symbol the UI Server is advised to -also expect a sign command. - @item GPGME_ENCRYPT_SYMMETRIC @since{1.7.0} @@ -7596,8 +7581,6 @@ case the state of @var{ctx} is not modified). @c ******************* Appendices ************************* @c ********************************************************** -@include uiserver.texi - @node Debugging @appendix How to solve problems @cindex debug diff --git a/doc/uiserver.texi b/doc/uiserver.texi deleted file mode 100644 index e001d120..00000000 --- a/doc/uiserver.texi +++ /dev/null @@ -1,621 +0,0 @@ -@c uiserver.texi -*- mode: texinfo; coding: latin-1; -*- -@c Specification of the UI server protocol. -@c To be included by gpgme.texi - -@node UI Server Protocol -@appendix The GnuPG UI Server Protocol -@cindex UI server -@cindex user interface server - - -This section specifies the protocol used between clients and a User -Interface Server (UI server). This protocol helps to build a system -where all cryptographic operations are done by a server and the server -is responsible for all dialogs. Although @acronym{GPGME} has no direct -support for this protocol it is believed that servers will utilize the -@acronym{GPGME} library; thus having the specification included in this -manual is an appropriate choice. This protocol should be referenced as -`The GnuPG UI Server Protocol'. - -@noindent -A server needs to implement these commands:@footnote{In all examples we -assume that the connection has already been established; see the Assuan -manual for details.} - -@menu -* UI Server Encrypt:: Encrypt a message. -* UI Server Sign:: Sign a message. -* UI Server Decrypt:: Decrypt a message. -* UI Server Verify:: Verify a message. -* UI Server Set Input Files:: Specifying the input files to operate on. -* UI Server Sign/Encrypt Files:: Encrypting and signing files. -* UI Server Verify/Decrypt Files:: Decrypting and verifying files. -* UI Server Import/Export Keys:: Managing certificates. -* UI Server Checksum Files:: Create and verify checksums for files. -* Miscellaneous UI Server Commands:: Commands not related to a specific operation. -@end menu - - - -@node UI Server Encrypt -@section UI Server: 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} [--binary] -Set the file descriptor to be used for the output (i.e. the encrypted -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 -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}] [-@w{}-expect-sign] - -This commands considers all recipients set so far and decides whether it -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} -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. - -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 UI Server Sign -@section UI Server: 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} [--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 -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 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 -prefixed with "@code{pgp-}". -@end deffn - - - -@node UI Server Decrypt -@section UI Server: 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] [-@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. 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 - - -@node UI Server Verify -@section UI Server: 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+ -@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 - - -@node UI Server Set Input Files -@section UI Server: Specifying the input files to operate on. - -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 [--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). 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 - - -@node UI Server Sign/Encrypt Files -@section UI Server: Encrypting and signing files. - -First, the input files need to be specified by one or more -@code{FILE} commands. Afterwards, the actual operation is requested: - -@deffn Command ENCRYPT_FILES --nohup -@deffnx Command SIGN_FILES --nohup -@deffnx Command ENCRYPT_SIGN_FILES --nohup -Request that the files specified by @code{FILE} are encrypted and/or -signed. The command selects the default action. The UI server may -allow the user to change this default afterwards interactively, and -even abort the operation or complete it only on some of the selected -files and directories. - -What it means to encrypt or sign a file or directory is specific to -the preferences of the user, the functionality the UI server provides, -and the selected protocol. Typically, for each input file a new file -is created under the original filename plus a protocol specific -extension (like @code{.gpg} or @code{.sig}), which contain the -encrypted/signed file or a detached signature. For directories, the -server may offer multiple options to the user (for example ignore or -process recursively). - -The @code{ENCRYPT_SIGN_FILES} command requests a combined sign and -encrypt operation. It may not be available for all protocols (for -example, it is available for OpenPGP but not for CMS). - -The option @code{--nohup} is mandatory. It is currently unspecified -what should happen if @code{--nohup} is not present. Because -@code{--nohup} is present, the server always returns @code{OK} -promptly, and completes the operation asynchronously. -@end deffn - - -@node UI Server Verify/Decrypt Files -@section UI Server: Decrypting and verifying files. - -First, the input files need to be specified by one or more -@code{FILE} commands. Afterwards, the actual operation is requested: - -@deffn Command DECRYPT_FILES --nohup -@deffnx Command VERIFY_FILES --nohup -@deffnx Command DECRYPT_VERIFY_FILES --nohup -Request that the files specified by @code{FILE} are decrypted and/or -verified. The command selects the default action. The UI server may -allow the user to change this default afterwards interactively, and -even abort the operation or complete it only on some of the selected -files and directories. - -What it means to decrypt or verify a file or directory is specific to -the preferences of the user, the functionality the UI server provides, -and the selected protocol. Typically, for decryption, a new file is -created for each input file under the original filename minus a -protocol specific extension (like @code{.gpg}) which contains the -original plaintext. For verification a status is displayed for each -signed input file, indicating if it is signed, and if yes, if the -signature is valid. For files that are signed and encrypted, the -@code{VERIFY} command transiently decrypts the file to verify the -enclosed signature. For directories, the server may offer multiple -options to the user (for example ignore or process recursively). - -The option @code{--nohup} is mandatory. It is currently unspecified -what should happen if @code{--nohup} is not present. Because -@code{--nohup} is present, the server always returns @code{OK} -promptly, and completes the operation asynchronously. -@end deffn - - -@node UI Server Import/Export Keys -@section UI Server: Managing certificates. - -First, the input files need to be specified by one or more -@code{FILE} commands. Afterwards, the actual operation is requested: - -@deffn Command IMPORT_FILES --nohup -Request that the certificates contained in the files specified by -@code{FILE} are imported into the local certificate databases. - -For directories, the server may offer multiple options to the user -(for example ignore or process recursively). - -The option @code{--nohup} is mandatory. It is currently unspecified -what should happen if @code{--nohup} is not present. Because -@code{--nohup} is present, the server always returns @code{OK} -promptly, and completes the operation asynchronously. -@end deffn - -FIXME: It may be nice to support an @code{EXPORT} command as well, -which is enabled by the context menu of the background of a directory. - - -@node UI Server Checksum Files -@section UI Server: Create and verify checksums for files. - -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 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 -directories, the server may offer multiple options to the user (for -example ignore or process recursively). - -The option @code{--nohup} is mandatory. It is currently unspecified -what should happen if @code{--nohup} is not present. Because -@code{--nohup} is present, the server always returns @code{OK} -promptly, and completes the operation asynchronously. -@end deffn - - -@deffn Command CHECKSUM_VERIFY_FILES --nohup -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 -of the user and the functionality provided by the UI server. For -directories, the server may offer multiple options to the user (for -example ignore or process recursively). - -If the source storage of previously created checksums is available to -the user through the Windows shell, this command may also accept such -checksum files as @code{FILE} arguments. In this case, the UI server -should instead verify the checksum of the referenced files as if they -were given as INPUT files. - -The option @code{--nohup} is mandatory. It is currently unspecified -what should happen if @code{--nohup} is not present. Because -@code{--nohup} is present, the server always returns @code{OK} -promptly, and completes the operation asynchronously. -@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 UI Server Commands -@section Miscellaneous UI Server 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 -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 -certificate manager). The client expects that the key manager is brought -into the foregound and that this command immediately 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 -immediately 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] [-@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 -@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. - -The option @option{--protocol} may be used to give the server a hint on -which signing protocol should be preferred. -@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