The GnuPG UI Server Protocol
****************************

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 GPGME has no direct support for this protocol it is believed that servers will utilize the 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'.

A server needs to implement these commands: (In all examples we assume that the connection has already been established; see the Assuan manual for details.)

UI Server: Encrypt a Message
============================

Before encryption can be done the recipients must be set using the command:

 -- Command: RECIPIENT STRING

     Set the recipient for the encryption.  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 ENCRYPT command.  All RECIPIENT commands are cumulative until a successful ENCRYPT command or until a RESET command. Linefeeds are obviously not allowed in STRING and should be folded into spaces (which are equivalent).

To tell the server the source and destination of the data, the next two commands are to be used:

 -- Command: INPUT FD=N
     Set the file descriptor for the message to be encrypted to N.  The message send to the server is binary encoded.

     GpgOL is a Windows only program, thus 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 DuplicateHandle needs to be used to duplicate a handle to the server process.  This is the reason that the server needs to implement the GETINFO pid command.  Sending this command a second time replaces the file descriptor set by the last one.

 -- Command: OUTPUT FD=N [--binary]
     Set the file descriptor to be used for the output (i.e. the encrypted message) to N.  If the option --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 INPUT command.

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:

 -- Command: ENCRYPT --protocol=NAME

     This command reads the plaintext from the file descriptor set by the INPUT command, encrypts it and writes the ciphertext to the file descriptor set by the 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.

     Because GpgOL uses a streaming mode of operation the server is not allowed to auto select the protocol and must obey to the mandatory PROTOCOL parameter:

     OpenPGP
          Use the OpenPGP protocol (RFC-2440).

     CMS
          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:

 -- Command: PREP_ENCRYPT [--protocol=NAME] [--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 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 ENCRYPT command is send.  The --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 --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 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:

 -- Status line: PROTOCOL NAME
     Advise the client to use the protocol NAME for the ENCRYPT command.  The valid protocol names are listed under the description of the ENCRYPT command.  The server shall emit exactly one PROTOCOL status line.

Here is an example of a complete encryption sequence; client lines are indicated by a C:, server responses by C::

       RESET
       OK
       RECIPIENT foo@example.net
       OK
       RECIPIENT bar@example.com
       OK
       PREP_ENCRYPT
       S PROTOCOL OpenPGP
       OK
       INPUT FD=17
       OK
       OUTPUT FD=18
       OK
       ENCRYPT
       OK

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:

 -- Command: INPUT FD=N
     Set the file descriptor for the message to be signed to N.  The message send to the server is binary encoded.  For details on the file descriptor, see the description of INPUT in the ENCRYPT section.

 -- Command: OUTPUT FD=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 --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 INPUT command.

To allow the server the selection of a non-default signing key the client may optionally use the SENDER command, see command SENDER.

The signing operation is then initiated by:

 -- Command: SIGN --protocol=NAME [--detached]
     Sign the data set with the INPUT command and write it to the sink set by OUTPUT.  NAME is the signing protocol used for the message. For a description of the allowed protocols see the ENCRYPT command.  With option --detached given, a detached signature is created; this is actually the usual way the command is used.

The client expects the server to send at least this status information before the final OK response:

 -- Status line: MICALG STRING
     The 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 gpgme_hash_algo_name to return the algorithm name as a string.  This string needs to be lowercased and for OpenPGP prefixed with "pgp-".

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:

 -- Command: INPUT FD=N
     Set the file descriptor for the message to be decrypted to 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 INPUT in the ENCRYPT section.

 -- Command: OUTPUT FD=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 INPUT in the ENCRYPT section.

The decryption is started with the command:

 -- Command: DECRYPT --protocol=NAME [--no-verify] [--export-session-key]
     NAME is the encryption protocol used for the message. For a description of the allowed protocols see the ENCRYPT command. This argument is mandatory.  If the 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 --export-session-key is given and the underlying engine knows how to export the session key, it will appear on a status line

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.

 -- Command: MESSAGE FD=N
     This command is used with detached signatures to set the file descriptor for the signed data to N. The data is binary encoded (used verbatim).  For details on the file descriptor, see the description of INPUT in the ENCRYPT section.

 -- Command: INPUT FD=N
     Set the file descriptor for the opaque message or the signature part of a detached signature to 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 INPUT in the ENCRYPT section.

 -- Command: OUTPUT FD=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 INPUT in the ENCRYPT section.

The verification is then started using:

 -- Command: VERIFY --protocol=NAME [--silent]
     NAME is the signing protocol used for the message. For a description of the allowed protocols see the ENCRYPT command. This argument is mandatory.  Depending on the combination of MESSAGE INPUT and OUTPUT commands, the server needs to select the appropriate verification mode:

     MESSAGE and INPUT
          This indicates a detached signature.  Output data is not applicable.

     INPUT
          This indicates an opaque signature.  As no output command has been given, the server is only required to check the signature.

     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.

With --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:

 -- Status line: SIGSTATUS FLAG DISPLAYSTRING
     Returns the status for the signature and a short string explaining the status.  Valid values for FLAG are:

     none
          The message has a signature but it could not not be verified due to a missing key.

     green
          The signature is fully valid.

     yellow
          The signature is valid but additional information was shown regarding the validity of the key.

     red
          The signature is not valid.

     DISPLAYSTRING is a percent-and-plus-encoded string with a short human readable description of the status.  For example

          S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net>

     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.

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 FILE commands:

 -- Command: FILE [--clear] NAME
     Add the file or directory NAME to the list of pathnames to be processed by the server.  The parameter 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 --clear is given, the list of files is cleared before adding NAME.

     Historical note: The original spec did not define --clear but the keyword --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.

UI Server: Encrypting and signing files.
========================================

First, the input files need to be specified by one or more FILE commands.  Afterwards, the actual operation is requested:

 -- Command: ENCRYPT_FILES --nohup
 -- Command: SIGN_FILES --nohup
 -- Command: ENCRYPT_SIGN_FILES --nohup
     Request that the files specified by 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 .gpg or .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 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 --nohup is mandatory.  It is currently unspecified what should happen if --nohup is not present.  Because --nohup is present, the server always returns OK promptly, and completes the operation asynchronously.

UI Server: Decrypting and verifying files.
==========================================

First, the input files need to be specified by one or more FILE commands.  Afterwards, the actual operation is requested:

 -- Command: DECRYPT_FILES --nohup
 -- Command: VERIFY_FILES --nohup
 -- Command: DECRYPT_VERIFY_FILES --nohup
     Request that the files specified by 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 .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 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 --nohup is mandatory.  It is currently unspecified what should happen if --nohup is not present.  Because --nohup is present, the server always returns OK promptly, and completes the operation asynchronously.

UI Server: Managing certificates.
=================================

First, the input files need to be specified by one or more FILE commands.  Afterwards, the actual operation is requested:

 -- Command: IMPORT_FILES --nohup
     Request that the certificates contained in the files specified by 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 --nohup is mandatory.  It is currently unspecified what should happen if --nohup is not present.  Because --nohup is present, the server always returns OK promptly, and completes the operation asynchronously.

FIXME: It may be nice to support an EXPORT command as well, which is enabled by the context menu of the background of a directory.

UI Server: Create and verify checksums for files.
=================================================

First, the input files need to be specified by one or more FILE commands.  Afterwards, the actual operation is requested:

 -- Command: CHECKSUM_CREATE_FILES --nohup
     Request that checksums are created for the files specified by 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 --nohup is mandatory.  It is currently unspecified what should happen if --nohup is not present.  Because --nohup is present, the server always returns OK promptly, and completes the operation asynchronously.

 -- Command: CHECKSUM_VERIFY_FILES --nohup
     Request that checksums are created for the files specified by 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 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 --nohup is mandatory.  It is currently unspecified what should happen if --nohup is not present.  Because --nohup is present, the server always returns OK promptly, and completes the operation asynchronously.

Miscellaneous UI Server Commands
================================

The server needs to implement the following commands which are not related to a specific command:

 -- Command: GETINFO WHAT
     This is a multi purpose command, commonly used to return a variety of information.  The required subcommands as described by the WHAT parameter are:

     pid
          Return the process id of the server in decimal notation using an Assuan 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:

 -- Command option: window-id NUMBER
     The NUMBER represents the native window ID of the clients current window.  On Windows systems this is a windows handle (HWND) and on X11 systems it is the X Window ID.  The number needs to be given as a hexadecimal value so that it is easier to convey pointer values (e.g. HWND).

A client may want to fire up the certificate manager of the server.  To do this it uses the Assuan command:

 -- 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).

A client may want to fire up the configuration dialog of the server.  To do this it uses the Assuan command:

 -- 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).

When doing an operation on a mail, it is useful to let the server know the address of the sender:

 -- Command: SENDER [--info] [--protocol=NAME] EMAIL
     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 RESET command.  A second command overrides the effect of the first one; if EMAIL is not given and --info is not used, the server shall use the default signing key.

     If 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 --protocol may be used to give the server a hint on which signing protocol should be preferred.

To allow the UI-server to visually identify a running operation or to associate operations the server MAY support the command:

 -- Command: SESSION NUMBER [STRING]
     The NUMBER is an arbitrary value, a server may use to associate simultaneous running sessions.  It is a 32 bit unsigned integer with 0 as a special value indicating that no session association shall be done.

     If 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 RESET undoes the effect of this command.