2004-02-23 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 numbers are
86 0 and 1.  0 often has a special meaning in this context as it actually
87 negates setting the option one or more times.
88
89 If the option takes a number argument (ALT-TYPE is 2 or 3), and it can
90 only occur once (LIST flag is not set), then the option argument is
91 either empty if the option is not set, or it is a number.  A number is
92 a string that begins with an optional minus character, followed by one
93 or more digits.  The number must fit into an integer variable
94 (unsigned or signed, depending on ALT-TYPE).
95
96 If the option takes a number argument and it can occur more than once,
97 then the option argument is either empty, or it is a comma-separated
98 list of numbers as described above.
99
100 If the option takes a string argument (ALT-TYPE is 1), and it can only
101 occur once (LIST flag is not set) then the option argument is either
102 empty if the option is not set, or it starts with a double quote
103 character (") followed by a percent-escaped string that is the
104 argument value.  Note that there is only a leading double quote
105 character, no trailing one.  The double quote character is only needed
106 to be able to differentiate between no value and the empty string as
107 value.
108
109 If the option takes a string argument and it can occur more than once,
110 then the option argument is either empty or it starts with a double
111 quote character (") followed by a comma-separated list of
112 percent-escaped strings.  Obviously any commas in the individual
113 strings must be percent-escaped.
114
115
116 FIXME: Document the active language and active character set.  Allow
117 to change it via the command line?
118
119
120 Components
121 ==========
122
123 A component is a set of configuration options that semantically belong
124 together.  Furthermore, several changes to a component can be made in
125 an atomic way with a single operation.  The GUI could for example
126 provide a menu with one entry for each component, or a window with one
127 tabulator sheet per component.
128
129 The following interface is provided to list the available components:
130
131 Command --list-components
132 -------------------------
133
134 Outputs a list of all components available, one per line.  The format
135 of each line is:
136
137 NAME:DESCRIPTION
138
139 NAME
140
141 This field contains a name tag of the component.  The name tag is used
142 to specify the component in all communication with GPGConf.  The name
143 tag is to be used verbatim.  It is not in any escaped format.
144
145 DESCRIPTION
146
147 The string in this field contains a human-readable description of the
148 component.  It can be displayed to the user of the GUI for
149 informational purposes.  It is percent-escaped and localized.
150
151 Example:
152 $ gpgconf --list-components
153 gpg-agent:GPG Agent
154 dirmngr:CRL Manager
155
156
157 OPTIONS
158 =======
159
160 Every component contains one or more options.  Options may belong to a
161 group.  The following command lists all options and the groups they
162 belong to:
163
164 Command --list-options COMPONENT
165 --------------------------------
166
167 Lists all options (and the groups they belong to) in the component
168 COMPONENT.  COMPONENT is the string in the field NAME in the
169 output of the --list-components command.
170
171 There is one line for each option and each group.  First come all
172 options that are not in any group.  Then comes a line describing a
173 group.  Then come all options that belong into each group.  Then comes
174 the next group and so on.
175
176 The format of each line is:
177
178 NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:VALUE
179
180 NAME
181
182 This field contains a name tag for the group or option.  The name tag
183 is used to specify the group or option in all communication with
184 GPGConf.  The name tag is to be used verbatim.  It is not in any
185 escaped format.
186
187 FLAGS
188
189 The flags field contains an unsigned number.  Its value is the
190 OR-wise combination of the following flag values:
191
192         1 group         If this flag is set, this is a line describing
193                         a group and not an option.
194   O     2 optional arg  If this flag is set, the argument is optional.
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
200 Flags marked with a 'O' are only defined for options (ie, if the GROUP
201 flag is not set).
202
203 LEVEL
204
205 This field is defined for options and for groups.  It contains an
206 unsigned number that specifies the expert level under which this group
207 or option should be displayed.  The following expert levels are
208 defined for options (they have analogous meaning for groups):
209
210         0 basic         This option should always be offered to the user.
211         1 advanced      This option may be offered to advanced users.
212         2 expert        This option should only be offered to expert users.
213         3 invisible     This option should normally never be displayed,
214                         not even to expert users.
215         4 internal      This option is for internal use only.  Ignore it.
216
217 The level of a group will always be the lowest level of all options it
218 contains.
219
220 DESCRIPTION
221
222 This field is defined for options and groups.  The string in this
223 field contains a human-readable description of the option or group.
224 It can be displayed to the user of the GUI for informational purposes.
225 It is percent-escaped and localized.
226
227 TYPE
228
229 This field is only defined for options.  It contains an unsigned
230 number that specifies the type of the option's argument, if any.
231 The following types are defined:
232
233         0 none          No argument allowed.
234         1 string        An unformatted string.
235         2 int32         A signed integer number.
236         3 uint32        An unsigned integer number.
237         4 pathname      A string that describes the pathname of a file.
238                         The file does not necessarily need to exist.
239         5 ldap server   A string that describes an LDAP server in the format
240                         HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN.
241
242 More types will be added in the future.  Please see the ALT-TYPE field
243 for information on how to cope with unknown types.
244
245 ALT-TYPE
246
247 This field is identical to TYPE, except that only the types 0 to 3 are
248 allowed.  The GUI is expected to present the user the option in the
249 format specified by TYPE.  But if the argument type TYPE is not
250 supported by the GUI, it can still display the option in the more
251 generic basic type ALT-TYPE.  The GUI must support the basic types 0
252 to 3 to be able to display all options.
253
254 ARGNAME
255
256 This field is only defined for options with an argument type TYPE that
257 is not 0.  In this case it may contain a percent-escaped and localised
258 string that gives a short name for the argument.  The field may also
259 be empty, though, in which case a short name is not known.
260
261 DEFAULT
262
263 This field is defined only for options.  Its format is that of an
264 option argument (see section Format Conventions for details).  If the
265 default value is empty, then no default is known.  Otherwise, the
266 value specifies the default value for this option.  Note that this
267 field is also meaningful if the option itself does not take a real
268 argument.
269
270 VALUE
271
272 This field is defined only for options.  Its format is that of an
273 option argument.  If it is empty, then the option is not explicitely
274 set in the current configuration, and the default applies (if any).
275 Otherwise, it contains the current value of the option.  Note that
276 this field is also meaningful if the option itself does not take a
277 real argument.
278
279
280 CHANGING OPTIONS
281 ================
282
283 To change the options for a component, you must provide them in the
284 following format:
285
286 NAME:NEW-VALUE
287
288 NAME
289
290 This is the name of the option to change.
291
292 NEW-VALUE
293
294 The new value for the option.  The format is that of an option
295 argument.  If it is empty (or the field is omitted), the option will
296 be deleted, so that the default value is used.  Otherwise, the option
297 will be set to the specified value.
298
299 Option --runtime
300 ----------------
301
302 If this option is set, the changes will take effect at run-time, as
303 far as this is possible.  Otherwise, they will take effect at the next
304 start of the respective backend programs.
305
306
307 BACKENDS
308 ========
309
310 Backends should support the following commands:
311
312 Command --gpgconf-list
313 ----------------------
314
315 List the location of the configuration file, and all default values of
316 all options.  The location of the configuration file must be an
317 absolute pathname.
318
319 Example:
320 $ dirmngr --gpgconf-list
321 gpgconf-config-file:/mnt/marcus/.gnupg/dirmngr.conf
322 ldapservers-file:/mnt/marcus/.gnupg/dirmngr_ldapservers.conf
323 add-servers:0
324 max-replies:10