File: gpgme.info,  Node: UI Server Encrypt,  Next: UI Server Sign,  Up: UI Server Protocol

A.1 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::

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