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