2004-02-26 Marcus Brinkmann <marcus@g10code.de>
[gnupg.git] / tools / README.gpgconf
1 ============
2   GPG Conf
3 ============
4
5 CONCEPT
6 =======
7
8 gpgconf provides access to the configuration of one or more components
9 of the GnuPG system.  These components correspond more or less to the
10 programs that exist in the GnuPG framework, like GnuPG, GPGSM,
11 DirMngr, etc.  But this is not a strict one-to-one relationship.  Not
12 all configuration options are available through GPGConf.  GPGConf
13 provides a generic and abstract method to access the most important
14 configuration options that can feasibly be controlled via such a
15 mechanism.
16
17 GPGConf can be used to gather and change the options available in each
18 component, and can also provide their default values.  GPGConf will
19 give detailed type information that can be used to restrict the user's
20 input without making an attempt to commit the changes.
21
22 GPGConf provides the backend of a configuration editor.  The
23 configuration editor would usually be a graphical user interface
24 program, that allows to display the current options, their default
25 values, and allows the user to make changes to the options.  These
26 changes can then be made active with GPGConf again.  Such a program
27 that uses GPGConf in this way will be called 'GUI' throughout this
28 document.
29
30
31 Format Conventions
32 ==================
33
34 Some lines in the output of GPGConf contain a list of colon-separated
35 fields.  The following conventions apply:
36
37 The GUI program is required to strip off trailing newline and/or carriage
38 return characters from the output.
39
40 GPGConf will never leave out fields.  If a certain version documents a
41 certain field, this field will always be present in all GPGConf
42 versions from that time on.
43
44 Future versions of GPGConf might append fields to the list.  New
45 fields will always be separated from the previously last field by a
46 colon separator.  The GUI should be prepared to parse the last field
47 it knows about up until a colon or end of line.
48
49 Not all fields are defined under all conditions.  You are required to
50 ignore the content of undefined fields.
51
52 Some fields contain strings that are not escaped in any way.  Such
53 fields are described to be used "verbatim".  These fields will never
54 contain a colon character (for obvious reasons).  No de-escaping or
55 other formatting is required to use the field content.  This is for
56 easy parsing of the output, when it is known that the content can
57 never contain any special characters.
58
59 Some fields contain strings that are described to be
60 "percent-escaped".  Such strings need to be de-escaped before their
61 content can be presented to the user.  A percent-escaped string is
62 de-escaped by replacing all occurences of %XY by the byte that has the
63 hexadecimal value XY.  X and Y are from the set { '0'..'9', 'a'..'f' }.
64
65 Some fields contain strings that are described to be "localised".  Such
66 strings are translated to the active language and formatted in the
67 active character set.
68
69 Some fields contain an unsigned number.  This number will always fit
70 into a 32-bit unsigned integer variable.  The number may be followed
71 by a space, followed by a human readable description of that value.
72 You should ignore everything in the field that follows the number.
73
74 Some fields contain a signed number.  This number will always fit into
75 a 32-bit signed integer variable.  The number may be followed by a
76 space, followed by a human readable description of that value.  You
77 should ignore everything in the field that follows the number.
78
79 Some fields contain an option argument.  The format of an option
80 argument depends on the type of the option and on some flags:
81
82 The simplest case is that the option does not take an argument at all
83 (TYPE is 0).  Then the option argument is either empty if the option
84 is not set, or an unsigned number that specifies how often the option
85 occurs.  If the LIST flag is not set, then the only valid number is 1.
86 Options that don't take an argument never have the "default" flag set.
87
88 If the option takes a number argument (ALT-TYPE is 2 or 3), and it can
89 only occur once (LIST flag is not set), then the option argument is
90 either empty if the option is not set, or it is a number.  A number is
91 a string that begins with an optional minus character, followed by one
92 or more digits.  The number must fit into an integer variable
93 (unsigned or signed, depending on ALT-TYPE).
94
95 If the option takes a number argument and it can occur more than once,
96 then the option argument is either empty, or it is a comma-separated
97 list of numbers as described above.
98
99 If the option takes a string argument (ALT-TYPE is 1), and it can only
100 occur once (LIST flag is not set) then the option argument is either
101 empty if the option is not set, or it starts with a double quote
102 character (") followed by a percent-escaped string that is the
103 argument value.  Note that there is only a leading double quote
104 character, no trailing one.  The double quote character is only needed
105 to be able to differentiate between no value and the empty string as
106 value.
107
108 If the option takes a string argument and it can occur more than once,
109 then the option argument is either empty or it starts with a double
110 quote character (") followed by a comma-separated list of
111 percent-escaped strings.  Obviously any commas in the individual
112 strings must be percent-escaped.
113
114
115 FIXME: Document the active language and active character set.  Allow
116 to change it via the command line?
117
118
119 Components
120 ==========
121
122 A component is a set of configuration options that semantically belong
123 together.  Furthermore, several changes to a component can be made in
124 an atomic way with a single operation.  The GUI could for example
125 provide a menu with one entry for each component, or a window with one
126 tabulator sheet per component.
127
128 The following interface is provided to list the available components:
129
130 Command --list-components
131 -------------------------
132
133 Outputs a list of all components available, one per line.  The format
134 of each line is:
135
136 NAME:DESCRIPTION
137
138 NAME
139
140 This field contains a name tag of the component.  The name tag is used
141 to specify the component in all communication with GPGConf.  The name
142 tag is to be used verbatim.  It is not in any escaped format.
143
144 DESCRIPTION
145
146 The string in this field contains a human-readable description of the
147 component.  It can be displayed to the user of the GUI for
148 informational purposes.  It is percent-escaped and localized.
149
150 Example:
151 $ gpgconf --list-components
152 gpg-agent:GPG Agent
153 dirmngr:CRL Manager
154
155
156 OPTIONS
157 =======
158
159 Every component contains one or more options.  Options may belong to a
160 group.  The following command lists all options and the groups they
161 belong to:
162
163 Command --list-options COMPONENT
164 --------------------------------
165
166 Lists all options (and the groups they belong to) in the component
167 COMPONENT.  COMPONENT is the string in the field NAME in the
168 output of the --list-components command.
169
170 There is one line for each option and each group.  First come all
171 options that are not in any group.  Then comes a line describing a
172 group.  Then come all options that belong into each group.  Then comes
173 the next group and so on.
174
175 The format of each line is:
176
177 NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE
178
179 NAME
180
181 This field contains a name tag for the group or option.  The name tag
182 is used to specify the group or option in all communication with
183 GPGConf.  The name tag is to be used verbatim.  It is not in any
184 escaped format.
185
186 FLAGS
187
188 The flags field contains an unsigned number.  Its value is the
189 OR-wise combination of the following flag values:
190
191          1 group        If this flag is set, this is a line describing
192                         a group and not an option.
193   O      2 optional arg If this flag is set, the argument is optional.
194                         This is never set for arg type 0 (none) options.
195   O      4 list         If this flag is set, the option can be given
196                         multiple times.
197   O      8 runtime      If this flag is set, the option can be changed
198                         at runtime.
199   O     16 default      If this flag is set, a default value is available.
200   O     32 default desc If this flag is set, a (runtime) default is available.
201                         This and the 'default' flag are mutually exclusive.
202   O     64 no arg desc  If this flag is set, and the 'optional arg' flag
203                         is set, then the option has a special meaning if no
204                         argument is given.
205
206 Flags marked with a 'O' are only defined for options (ie, if the GROUP
207 flag is not set).
208
209 LEVEL
210
211 This field is defined for options and for groups.  It contains an
212 unsigned number that specifies the expert level under which this group
213 or option should be displayed.  The following expert levels are
214 defined for options (they have analogous meaning for groups):
215
216         0 basic         This option should always be offered to the user.
217         1 advanced      This option may be offered to advanced users.
218         2 expert        This option should only be offered to expert users.
219         3 invisible     This option should normally never be displayed,
220                         not even to expert users.
221         4 internal      This option is for internal use only.  Ignore it.
222
223 The level of a group will always be the lowest level of all options it
224 contains.
225
226 DESCRIPTION
227
228 This field is defined for options and groups.  The string in this
229 field contains a human-readable description of the option or group.
230 It can be displayed to the user of the GUI for informational purposes.
231 It is percent-escaped and localized.
232
233 TYPE
234
235 This field is only defined for options.  It contains an unsigned
236 number that specifies the type of the option's argument, if any.
237 The following types are defined:
238
239         Basic types
240          0 none         No argument allowed.
241          1 string       An unformatted string.
242          2 int32        A signed integer number.
243          3 uint32       An unsigned integer number.
244
245         Complex types
246         32 pathname     A string that describes the pathname of a file.
247                         The file does not necessarily need to exist.
248         33 ldap server  A string that describes an LDAP server in the format
249                         HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN.
250
251 More types will be added in the future.  Please see the ALT-TYPE field
252 for information on how to cope with unknown types.
253
254 ALT-TYPE
255
256 This field is identical to TYPE, except that only the types 0 to 31
257 are allowed.  The GUI is expected to present the user the option in
258 the format specified by TYPE.  But if the argument type TYPE is not
259 supported by the GUI, it can still display the option in the more
260 generic basic type ALT-TYPE.  The GUI must support all the defined
261 basic types to be able to display all options.  More basic types may
262 be added in future versions.  If the GUI encounters a basic type it
263 doesn't support, it should report an error and abort the operation.
264
265 ARGNAME
266
267 This field is only defined for options with an argument type TYPE that
268 is not 0.  In this case it may contain a percent-escaped and localised
269 string that gives a short name for the argument.  The field may also
270 be empty, though, in which case a short name is not known.
271
272 DEFAULT
273
274 This field is defined only for options.  Its format is that of an
275 option argument (see section Format Conventions for details).  If the
276 default value is empty, then no default is known.  Otherwise, the
277 value specifies the default value for this option.  Note that this
278 field is also meaningful if the option itself does not take a real
279 argument.
280
281 ARGDEF
282
283 This field is defined only for options for which the "optional arg"
284 flag is set.  If the "no arg desc" flag is not set, its format is that
285 of an option argument (see section Format Conventions for details).
286 If the default value is empty, then no default is known.  Otherwise,
287 the value specifies the default value for this option.  If the "no arg
288 desc" flag is set, the field is either empty or contains a description
289 of the effect of this option if no argument is given.  Note that this
290 field is also meaningful if the option itself does not take a real
291 argument.
292
293 VALUE
294
295 This field is defined only for options.  Its format is that of an
296 option argument.  If it is empty, then the option is not explicitely
297 set in the current configuration, and the default applies (if any).
298 Otherwise, it contains the current value of the option.  Note that
299 this field is also meaningful if the option itself does not take a
300 real argument.
301
302
303 CHANGING OPTIONS
304 ================
305
306 To change the options for a component, you must provide them in the
307 following format:
308
309 NAME:FLAGS:NEW-VALUE
310
311 NAME
312
313 This is the name of the option to change.
314
315 FLAGS
316
317 The flags field contains an unsigned number.  Its value is the
318 OR-wise combination of the following flag values:
319
320         16 default      If this flag is set, the option is deleted and the
321                         default value is used instead (if applicable).
322
323 NEW-VALUE
324
325 The new value for the option.  This field is only defined if the
326 "default" flag is not set.  The format is that of an option argument.
327 If it is empty (or the field is omitted), the default argument is used
328 (only allowed if the argument is optional for this option).
329 Otherwise, the option will be set to the specified value.
330
331
332 Example:
333 To set the option force, which is of basic type 0 (none).
334 $ echo 'force:0:1' | gpgconf --change-options dirmngr
335 To delete the option force:
336 $ echo 'force:16:0' | gpgconf --change-options dirmngr
337
338
339 Option --runtime
340 ----------------
341
342 If this option is set, the changes will take effect at run-time, as
343 far as this is possible.  Otherwise, they will take effect at the next
344 start of the respective backend programs.
345
346
347 BACKENDS
348 ========
349
350 Backends should support the following commands:
351
352 Command --gpgconf-list
353 ----------------------
354
355 List the location of the configuration file, and all default values of
356 all options.  The location of the configuration file must be an
357 absolute pathname.
358
359 The format of each line is:
360
361 NAME:FLAGS:DEFAULT:ARGDEF
362
363 NAME
364
365 This field contains a name tag for the group or option.  The name tag
366 is used to specify the group or option in all communication with
367 GPGConf.  The name tag is to be used verbatim.  It is not in any
368 escaped format.
369
370 FLAGS
371
372 The flags field contains an unsigned number.  Its value is the
373 OR-wise combination of the following flag values:
374
375         16 default      If this flag is set, a default value is available.
376         32 default desc If this flag is set, a (runtime) default is available.
377                         This and the "default" flag are mutually exclusive.
378         64 no arg desc  If this flag is set, and the "optional arg" flag
379                         is set, then the option has a special meaning if no
380                         argument is given.
381
382 DEFAULT
383
384 This field is defined only for options.  Its format is that of an
385 option argument (see section Format Conventions for details).  If the
386 default value is empty, then no default is known.  Otherwise, the
387 value specifies the default value for this option.  Note that this
388 field is also meaningful if the option itself does not take a real
389 argument.
390
391 ARGDEF
392
393 This field is defined only for options for which the "optional arg"
394 flag is set.  If the "no arg desc" flag is not set, its format is that
395 of an option argument (see section Format Conventions for details).
396 If the default value is empty, then no default is known.  Otherwise,
397 the value specifies the default value for this option.  If the "no arg
398 desc" flag is set, the field is either empty or contains a description
399 of the effect of this option if no argument is given.  Note that this
400 field is also meaningful if the option itself does not take a real
401 argument.
402
403
404 Example:
405 $ dirmngr --gpgconf-list
406 gpgconf-config-file:/mnt/marcus/.gnupg/dirmngr.conf
407 ldapservers-file:/mnt/marcus/.gnupg/dirmngr_ldapservers.conf
408 add-servers:0
409 max-replies:10
410
411
412 TODO
413 ----
414
415 * Extend the backend interface to include gettext domain and
416 description, if available, to avoid repeating this information in
417 gpgconf.