2007-10-08 Marcus Brinkmann <marcus@g10code.de>
[gpgex.git] / doc / gpgex.texi
1 \input texinfo
2 @documentencoding ISO-8859-1
3 @setfilename gpgex.info
4 @include version.texi
5 @settitle The GpgEX Technical Manual
6
7 @dircategory GnuPG Plugin
8 @direntry
9 * gpgex: (gpgex).              An extension for the Windows shell.
10 @end direntry
11
12
13 @c Unify some of the indices.
14 @syncodeindex tp fn
15 @syncodeindex pg fn
16
17 @copying
18 This is @cite{The GpgEX Technical Manual} for @acronym{GpgEX} (version
19 @value{VERSION}, @value{UPDATED-MONTH}).
20
21 @iftex
22 Published by g10 Code GmbH@*
23 Hüttenstr. 61@*
24 40699 Erkrath, Germany
25 @end iftex
26
27 Copyright @copyright{} 2007 g10 Code GmbH
28
29 @quotation
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU General Public License as published by the
32 Free Software Foundation; either version 3 of the License, or (at your
33 option) any later version. The text of the license can be found in the
34 section entitled ``Copying''.
35 @end quotation
36 @end copying
37
38 @c
39 @c Titlepage
40 @c
41 @setchapternewpage odd
42 @titlepage 
43 @title The GpgEX Technical Manual
44 @subtitle Version @value{VERSION}
45 @subtitle @value{UPDATED-MONTH}
46
47 @sp 3
48
49 @sp 3
50
51 @author Werner Koch (@email{wk@@gnupg.org})
52
53 @page
54 @vskip 0pt plus 1filll
55 @insertcopying
56 @end titlepage
57
58 @ifnothtml
59 @contents
60 @page
61 @end ifnothtml
62
63 @c @ifhtml
64 @c @center @image{logo}
65 @c @end ifhtml
66
67 @ifnottex
68 @node Top
69 @top 
70
71 @insertcopying
72
73 @noindent
74 This file documents @acronym{GpgEX}; a GnuPG plugin for the Windows shell.
75 @end ifnottex
76
77
78 @menu
79 * Introduction::                How to use this manual.
80 * Assuan Protocol::             Description of the UI server protocol.
81
82 Appendices
83
84 * Copying::                     The GNU General Public License says how you
85                                 can copy and share this manual.
86
87 Indices
88
89 * Concept Index::               Index of concepts and programs.
90 * Function and Data Index::     Index of functions, variables and data types.
91
92 @end menu
93
94 @ifhtml
95 @page
96 @summarycontents
97 @contents
98 @end ifhtml
99
100 @c
101 @c  I N T R O
102 @c
103 @node Introduction
104 @chapter Introduction
105 Bla bla
106
107
108 @c
109 @c  P R O T O C O L  D E S C R I P T I O N
110 @c
111 @node Assuan Protocol
112 @chapter Description of the UI Server Protocol
113
114 This section describes the protocol used between @acronym{GpgEX} and the
115 User Interface Server (UI server).  All cryptographic operations are
116 done by this server and the server is responsible for all dialogs.  If a
117 a server is not available, @acronym{GpgEX} does not work.
118
119 We assume that the connection has already been established; see the
120 Assuan manual for details.
121
122 @menu
123 * Specifying input files::   Specifying the input files to operate on.
124 * Encrypt and sign files::   Encrypting and signing files.
125 * Decrypt and verify files:: Decrypting and verifying files.
126 * Checksum files::           Create and verify checksums for files.
127 * Miscellaneous commands::   Support functions.
128 @end menu
129
130
131 @node Specifying input files
132 @section Specifying the input files to operate on.
133
134 All commands operate on a number of input files or directories,
135 specified by one or more @code{INPUT} commands:
136
137 @deffn Command INPUT FILE=@var{name} [--continued]
138 Add the file or directory @var{name} to the list of pathnames to be
139 processed by the server.  The parameter @var{name} must be an absolute
140 path name (including the drive letter) and is percent espaced (in
141 particular, the characters %, = and white space characters are always
142 escaped).  The option @code{--continued} is present for all but the
143 last @code{INPUT} command.
144 @end deffn
145
146
147 @node Encrypt and sign files
148 @section Encrypting and signing files.
149
150 First, the input files need to be specified by one or more
151 @code{INPUT} commands.  Afterwards, the actual operation is requested:
152
153 @deffn Command ENCRYPT_FILES --nohup
154 @deffnx Command SIGN_FILES --nohup
155 @deffnx Command ENCRYPT_SIGN_FILES --nohup
156 Request that the files specified by @code{INPUT} are encrypted and/or
157 signed.  The command selects the default action.  The UI server may
158 allow the user to change this default afterwards interactively, and
159 even abort the operation or complete it only on some of the selected
160 files and directories.
161
162 What it means to encrypt or sign a file or directory is specific to
163 the preferences of the user, the functionality the UI server provides,
164 and the selected protocol.  Typically, for each input file a new file
165 is created under the original filename plus a protocol specific
166 extension (like @code{.gpg} or @code{.sig}), which contain the
167 encrypted/signed file or a detached signature.  For directories, the
168 server may offer multiple options to the user (for example ignore or
169 process recursively).
170
171 The @code{ENCRYPT_SIGN_FILES} command requests a combined sign and
172 encrypt operation.  It may not be available for all protocols (for
173 example, it is available for OpenPGP but not for CMS).
174
175 The option @code{--nohup} is mandatory.  It is currently unspecified
176 what should happen if @code{--nohup} is not present.  Because
177 @code{--nohup} is present, the server always returns @code{OK}
178 promptly, and completes the operation asynchronously.
179 @end deffn
180
181
182 @node Decrypt and verify files
183 @section Decrypting and verifying files.
184
185 First, the input files need to be specified by one or more
186 @code{INPUT} commands.  Afterwards, the actual operation is requested:
187
188 @deffn Command DECRYPT_FILES --nohup
189 @deffnx Command VERIFY_FILES --nohup
190 @deffnx Command DECRYPT_VERIFY_FILES --nohup
191 Request that the files specified by @code{INPUT} are decrypted and/or
192 verified.  The command selects the default action.  The UI server may
193 allow the user to change this default afterwards interactively, and
194 even abort the operation or complete it only on some of the selected
195 files and directories.
196
197 What it means to decrypt or verify a file or directory is specific to
198 the preferences of the user, the functionality the UI server provides,
199 and the selected protocol.  Typically, for decryption, a new file is
200 created for each input file under the original filename minus a
201 protocol specific extension (like @code{.gpg}) which contains the
202 original plaintext.  For verification a status is displayed for each
203 signed input file, indicating if it is signed, and if yes, if the
204 signature is valid.  For files that are signed and encrypted, the
205 @code{VERIFY} command transiently decrypts the file to verify the
206 enclosed signature.  For directories, the server may offer multiple
207 options to the user (for example ignore or process recursively).
208
209 The option @code{--nohup} is mandatory.  It is currently unspecified
210 what should happen if @code{--nohup} is not present.  Because
211 @code{--nohup} is present, the server always returns @code{OK}
212 promptly, and completes the operation asynchronously.
213 @end deffn
214
215
216 @node Checksum files
217 @section Create and verify checksums for files.
218
219 First, the input files need to be specified by one or more
220 @code{INPUT} commands.  Afterwards, the actual operation is requested:
221
222 @deffn Command CHECKSUM_CREATE_FILES --nohup
223 Request that checksums are created for the files specifed by
224 @code{INPUT}.  The choice of checksum algorithm and the destination
225 storage and format for the created checksums depend on the preferences
226 of the user and the functionality provided by the UI server.  For
227 directories, the server may offer multiple options to the user (for
228 example ignore or process recursively).
229
230 The option @code{--nohup} is mandatory.  It is currently unspecified
231 what should happen if @code{--nohup} is not present.  Because
232 @code{--nohup} is present, the server always returns @code{OK}
233 promptly, and completes the operation asynchronously.
234 @end deffn
235
236
237 @deffn Command CHECKSUM_VERIFY_FILES --nohup
238 Request that checksums are created for the files specifed by
239 @code{INPUT} and verified against previously created and stored
240 checksums.  The choice of checksum algorithm and the source storage
241 and format for previously created checksums depend on the preferences
242 of the user and the functionality provided by the UI server.  For
243 directories, the server may offer multiple options to the user (for
244 example ignore or process recursively).
245
246 If the source storage of previously created checksums is available to
247 the user through the Windows shell, this command may also accept such
248 checksum files as INPUT arguments.  In this case, the UI server should
249 instead verify the checksum of the referenced files as if they were
250 given as INPUT files.
251
252 The option @code{--nohup} is mandatory.  It is currently unspecified
253 what should happen if @code{--nohup} is not present.  Because
254 @code{--nohup} is present, the server always returns @code{OK}
255 promptly, and completes the operation asynchronously.
256 @end deffn
257
258
259 @c
260 @c M I S C E L L A N E O U S  C O M M A N D S
261 @c
262 @node Miscellaneous commands
263 @section Support functions.
264
265 @noindent
266 To allow the server to pop up the windows in the correct relation to the
267 client, the client is advised to tell the server by sending the option:
268
269 @deffn {Command option} window-id @var{number} 
270 The @var{number} represents the native window ID of the clients current
271 window.  On Windows systems this is a windows handle (@code{HWND}) and
272 on X11 systems it is the @code{X Window ID}.  The number needs to be
273 given as a hexadecimal value so that it is easier to convey pointer
274 values (e.g. @code{HWND}).
275 @end deffn
276
277
278 @include gpl.texi
279
280 @c
281 @c  I N D E X E S
282 @c
283 @node Concept Index
284 @unnumbered Concept Index
285 @printindex cp
286 @node Function and Data Index
287 @unnumbered Function and Data Index
288 @printindex fn
289
290 @bye
291
292
293 @c Local Variables:
294 @c coding: latin-1
295 @c End: