Before encryption can be done the recipients must be set using the command:
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
RECIPIENT commands are cumulative until a
ENCRYPT command or until a
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:
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.
DuplicateHandle needs to be used to duplicate a handle
to the server process. This is the reason that the server needs to
GETINFO pid command. Sending this command a second
time replaces the file descriptor set by the last one.
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
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:
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:
Use the OpenPGP protocol (RFC-2440).
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:
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
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 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
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:
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 email@example.com S: OK C: RECIPIENT firstname.lastname@example.org 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