Started documentation.
[gpgol.git] / doc / gpgol.texi
1 \input texinfo
2 @setfilename gpgol.info
3 @settitle The GpgOL Technical Manual
4
5 @dircategory GnuPG Plugin
6 @direntry
7 * gpgol: (gpgol).              An Outlook Plugin for GnuPG.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @macro mycopyrightnotice
17 Copyright @copyright{} 2007 g10 Code GmbH
18 @end macro
19 @macro mypermissionnotice
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU General Public License as published by the
22 Free Software Foundation; either version 3 of the License, or (at your
23 option) any later version. The text of the license can be found in the
24 section entitled ``Copying''.
25 @end macro
26
27
28
29 @ifinfo
30 This file documents @acronym{GpgOL}; a GnuPG plugin for Microsoft's
31 Outlook MUA.
32
33 This is @cite{The GpgOL Technical Manual} for @acronym{GpgOL} version
34 @value{VERSION}, last updated @value{UPDATED}.
35
36 @sp 1
37 @mycopyrightnotice{}
38 @sp 1
39 @mypermissionnotice{}
40 @end ifinfo
41
42
43 @iftex
44 @shorttitlepage The `GpgOL' Technical Manual
45 @titlepage
46 @center @titlefont{The `GpgOL'}
47 @sp 1
48 @center @titlefont{Technical Manual}
49 @sp 6
50 @center for version @value{VERSION}
51 @sp 1
52 @center last updated @value{UPDATED}
53 @sp 1
54 @author by Werner Koch, g10 Code GmbH
55 @email{wk@@gnupg.org}
56 @page
57 @vskip 0pt plus 1filll
58 @mycopyrightnotice{}
59 @sp 1
60 @mypermissionnotice{}
61 @end titlepage
62 @summarycontents
63 @contents
64 @page
65 @end iftex
66
67
68 @ifnottex
69 @node Top
70 @top Main Menu
71 This is @cite{The GpgOL Technical Manual} for @acronym{GpgOL} version
72 @value{VERSION}, last updated @value{UPDATED}.
73 @sp 1
74 @mycopyrightnotice{}
75 @sp 1
76 @mypermissionnotice{}
77 @sp 1
78 @end ifnottex
79
80
81 @menu
82 * Introduction::                How to use this manual.
83 * Assuan Protocol::             Description of the UI server protocol.
84
85 Appendices
86
87 * Copying::                     The GNU General Public License says how you
88                                 can copy and share this manual.
89
90 Indices
91
92 * Concept Index::               Index of concepts and programs.
93 * Function and Data Index::     Index of functions, variables and data types.
94
95 @end menu
96
97 @node Introduction
98 @chapter Introduction
99 Bla bla
100
101
102
103 @node Assuan Protocol
104 @chapter Description of the UI Server Protocol
105
106 This section descripes the protocol used between @acronym{GpgOL} and the
107 User Interface Server (UI server).  All cryptographic operations are
108 done by this server and teh server is responsible for all dialogs.  If a
109 a server is not available, @acronym{GpgOL} can only use a very limited
110 internal crypto server.
111
112 We assume that the connection has already been established; see the
113 Assuan manual for details.
114
115 @menu
116 * ENCRYPT::                  Encrypting a message.
117 * Miscellaneous Commands::   Commands not related to a specific operation.
118 @end menu
119
120
121
122 @node ENCRYPT
123 @section Encrypting a Message
124
125 Before encrytion can be done the recipients must be set using the
126 command:
127
128 @deffn Command RECIPIENT @var{string}
129
130 Set the recipient for the encryption.  @var{string} is an RFC-2822
131 recipient name.  This command may or may not check the recipient for
132 validity right away; if it does not all recipients are expected to be
133 checked at the time of the @code{ENCRYPT} command.  All @code{RECIPIENT}
134 commands are cumulative until a successful @code{ENCRYPT} command or
135 until a RESET command.  Linefeeds are obviously not allowed in
136 @var{string} and should be folded into spaces (which are equivalent).
137 @end deffn
138
139 @noindent
140 To tell the server the source and destination of the data, the next two
141 commands are to be used:
142
143 @deffn Command INPUT FD=@var{n}
144 Set the file descriptor for the message to be encrypted to @var{n}.  The
145 message send to the server is binary encoded. 
146
147 GpgOL is a Windows only program, thus @var{n} is not a libc file
148 descriptor but a regular system handle.  Given that the Assuan
149 connection works over a socket, it is not possible to use regular
150 inheritance to make the file descriptor available to the server.
151 Thus @code{DuplicateHandle} needs to be used to duplicate a handle
152 to the server process.  This is the reason that the server needs to
153 implement the @code{GETINFO pid} command.  Sending this command a second
154 time replaces the file descriptor set by the last one.
155 @c If @var{n} is not given, this commands uses the
156 @c %last file descriptor passed to the application.
157 @c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the
158 @c %Libassuan manual}, on how to do descriptor passing.
159 @end deffn
160
161 @deffn Command OUTPUT FD=@var{n}
162 Set the file descriptor to be used for the output (i.e. the encrypted
163 message) to @var{n}.  Binary encoding is expected.  For details on the
164 file descriptor, see the @code{INPUT} command.
165 @end deffn
166
167 @noindent  
168 The setting of the recipients, the data source and destination may
169 happen in any order, even intermixed.  If this has been done the actual
170 encryption operation is called using:
171
172 @deffn Command ENCRYPT --protocol=@var{name}
173
174 This command reads the plaintext from the file descriptor set by the
175 @code{INPUT} command, encrypts it and writes the ciphertext to the file
176 descriptor set by the @code{OUTPUT} command.  The server may (and
177 should) overlap readind and writing.  The recipients used for the
178 encryption are all the recipients set so far.  If any recipient is not
179 usable the server should take appropriate measures to notify the user
180 about the problem and may cancel the operation by returning an error
181 code.  The used file descriptors are a void after this command; the
182 recipient list is only cleared if the server returns success.
183
184 @noindent
185 Because GpgOL uses a streaming mode of operation the server is not
186 allowed to auto select the protocol and must obey to the mandatory
187 @var{protocol} parameter:
188
189 @table @code
190 @item OpenPGP
191 Use the OpenPGP protocol (RFC-2440).
192 @item CMS
193 Use the CMS (PKCS#7) protocol (RFC-3852).
194 @end table
195
196 @end deffn
197
198
199
200
201 @node Miscellaneous Commands
202 @section Miscellaneous Commands
203
204 The server needs to implement the following commands which are not
205 related to a specific command:
206
207 @deffn Command GETINFO @var{what}
208 This is a multi purpose command, commonly used to return a variety of
209 information.  The required subcommands as descriped by the @var{waht}
210 parameter are:
211
212 @table @code
213 @item pid
214 Return the process id of the server in decimal notation using an Assuan
215 data line.
216 @end table
217 @end deffn
218
219
220
221
222 @include gpl.texi
223
224
225 @node Concept Index
226 @unnumbered Concept Index
227 @printindex cp
228 @node Function and Data Index
229 @unnumbered Function and Data Index
230 @printindex fn
231 @bye