gpg: Improve function documentation and some comments.
[gnupg.git] / g10 / options.h
1 /* options.h
2  * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
3  *               2007, 2010, 2011 Free Software Foundation, Inc.
4  *
5  * This file is part of GnuPG.
6  *
7  * GnuPG is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 3 of the License, or
10  * (at your option) any later version.
11  *
12  * GnuPG is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, see <http://www.gnu.org/licenses/>.
19  */
20 #ifndef G10_OPTIONS_H
21 #define G10_OPTIONS_H
22
23 #include <sys/types.h>
24 #include <types.h>
25 #include "main.h"
26 #include "packet.h"
27 #include "../common/session-env.h"
28
29 #ifndef EXTERN_UNLESS_MAIN_MODULE
30 /* Norcraft can't cope with common symbols */
31 #if defined (__riscos__) && !defined (INCLUDED_BY_MAIN_MODULE)
32 #define EXTERN_UNLESS_MAIN_MODULE extern
33 #else
34 #define EXTERN_UNLESS_MAIN_MODULE
35 #endif
36 #endif
37
38 /* Declaration of a keyserver spec type.  The definition is found in
39    ../common/keyserver.h.  */
40 struct keyserver_spec;
41 typedef struct keyserver_spec *keyserver_spec_t;
42
43
44 /* Global options for GPG.  */
45 EXTERN_UNLESS_MAIN_MODULE
46 struct
47 {
48   int verbose;
49   int quiet;
50   unsigned debug;
51   int armor;
52   char *outfile;
53   estream_t outfp;  /* Hack, sometimes used in place of outfile.  */
54   off_t max_output;
55   int dry_run;
56   int autostart;
57   int list_only;
58   int textmode;
59   int expert;
60   const char *def_sig_expire;
61   int ask_sig_expire;
62   const char *def_cert_expire;
63   int ask_cert_expire;
64   int batch;        /* run in batch mode */
65   int answer_yes; /* answer yes on most questions */
66   int answer_no;  /* answer no on most questions */
67   int check_sigs; /* check key signatures */
68   int with_colons;
69   int with_key_data;
70   int with_icao_spelling; /* Print ICAO spelling with fingerprints.  */
71   int with_fingerprint; /* Option --with-fingerprint active.  */
72   int with_keygrip;     /* Option --with-keygrip active.  */
73   int with_secret;      /* Option --with-secret active.  */
74   int fingerprint; /* list fingerprints */
75   int list_sigs;   /* list signatures */
76   int print_pka_records;
77   int print_dane_records;
78   int no_armor;
79   int list_packets; /* list-packets mode: 1=normal, 2=invoked by command*/
80   int def_cipher_algo;
81   int force_mdc;
82   int disable_mdc;
83   int def_digest_algo;
84   int cert_digest_algo;
85   int compress_algo;
86   int compress_level;
87   int bz2_compress_level;
88   int bz2_decompress_lowmem;
89   const char *def_secret_key;
90   char *def_recipient;
91   int def_recipient_self;
92   strlist_t secret_keys_to_try;
93
94   int def_cert_level;
95   int min_cert_level;
96   int ask_cert_level;
97   int emit_version;       /* 0 = none,
98                              1 = major only,
99                              2 = major and minor,
100                              3 = full version,
101                              4 = full version plus OS string. */
102   int marginals_needed;
103   int completes_needed;
104   int max_cert_depth;
105   const char *homedir;
106   const char *agent_program;
107   const char *dirmngr_program;
108
109   /* Options to be passed to the gpg-agent */
110   session_env_t session_env;
111   char *lc_ctype;
112   char *lc_messages;
113
114   int skip_verify;
115   int skip_hidden_recipients;
116
117   /* TM_CLASSIC must be zero to accomodate trustdbs generated before
118      we started storing the trust model inside the trustdb. */
119   enum
120     {
121       TM_CLASSIC=0, TM_PGP=1, TM_EXTERNAL=2,
122       TM_ALWAYS, TM_DIRECT, TM_AUTO, TM_TOFU, TM_TOFU_PGP
123     } trust_model;
124   enum
125     {
126       TOFU_DB_AUTO=0, TOFU_DB_SPLIT, TOFU_DB_FLAT
127     } tofu_db_format;
128   /* TOFU_BINDING_BAD, TOFU_BINDING_ASK, TOFU_BINDING_AUTO, or
129      TOFU_BINDING_GOOD.  */
130   int tofu_default_policy;
131   int force_ownertrust;
132   enum
133     {
134       CO_GNUPG, CO_RFC4880, CO_RFC2440,
135       CO_PGP6, CO_PGP7, CO_PGP8
136     } compliance;
137   enum
138     {
139       KF_SHORT, KF_LONG, KF_0xSHORT, KF_0xLONG
140     } keyid_format;
141   int shm_coprocess;
142   const char *set_filename;
143   strlist_t comments;
144   int throw_keyids;
145   const char *photo_viewer;
146   int s2k_mode;
147   int s2k_digest_algo;
148   int s2k_cipher_algo;
149   unsigned char s2k_count; /* This is the encoded form, not the raw
150                               count */
151   int not_dash_escaped;
152   int escape_from;
153   int lock_once;
154   keyserver_spec_t keyserver;  /* The list of configured keyservers.  */
155   struct
156   {
157     unsigned int options;
158     unsigned int import_options;
159     unsigned int export_options;
160     char *http_proxy;
161   } keyserver_options;
162   int exec_disable;
163   int exec_path_set;
164   unsigned int import_options;
165   unsigned int export_options;
166   unsigned int list_options;
167   unsigned int verify_options;
168   const char *def_preference_list;
169   const char *def_keyserver_url;
170   prefitem_t *personal_cipher_prefs;
171   prefitem_t *personal_digest_prefs;
172   prefitem_t *personal_compress_prefs;
173   struct weakhash *additional_weak_digests;
174   int no_perm_warn;
175   int no_mdc_warn;
176   char *temp_dir;
177   int no_encrypt_to;
178   int interactive;
179   struct notation *sig_notations;
180   struct notation *cert_notations;
181   strlist_t sig_policy_url;
182   strlist_t cert_policy_url;
183   strlist_t sig_keyserver_url;
184   strlist_t cert_subpackets;
185   strlist_t sig_subpackets;
186   int allow_non_selfsigned_uid;
187   int allow_freeform_uid;
188   int no_literal;
189   ulong set_filesize;
190   int fast_list_mode;
191   int legacy_list_mode;
192   int ignore_time_conflict;
193   int ignore_valid_from;
194   int ignore_crc_error;
195   int ignore_mdc_error;
196   int command_fd;
197   const char *override_session_key;
198   int show_session_key;
199
200   const char *gpg_agent_info;
201   int try_all_secrets;
202   int no_expensive_trust_checks;
203   int no_sig_cache;
204   int no_auto_check_trustdb;
205   int preserve_permissions;
206   int no_homedir_creation;
207   struct groupitem *grouplist;
208   int mangle_dos_filenames;
209   int enable_progress_filter;
210   unsigned int screen_columns;
211   unsigned int screen_lines;
212   byte *show_subpackets;
213   int rfc2440_text;
214
215   /* If true, let write failures on the status-fd exit the process. */
216   int exit_on_status_write_error;
217
218   /* If > 0, limit the number of card insertion prompts to this
219      value. */
220   int limit_card_insert_tries;
221
222 #ifdef ENABLE_CARD_SUPPORT
223   /* FIXME: We don't needs this here as it is done in scdaemon. */
224   const char *ctapi_driver; /* Library to access the ctAPI. */
225   const char *pcsc_driver;  /* Library to access the PC/SC system. */
226   int disable_ccid;    /* Disable the use of the internal CCID driver. */
227 #endif /*ENABLE_CARD_SUPPORT*/
228
229   struct
230   {
231     /* If set, require an 0x19 backsig to be present on signatures
232        made by signing subkeys.  If not set, a missing backsig is not
233        an error (but an invalid backsig still is). */
234     unsigned int require_cross_cert:1;
235
236     unsigned int use_embedded_filename:1;
237     unsigned int utf8_filename:1;
238     unsigned int dsa2:1;
239     unsigned int allow_multiple_messages:1;
240     unsigned int allow_weak_digest_algos:1;
241     unsigned int large_rsa:1;
242   } flags;
243
244   /* Linked list of ways to find a key if the key isn't on the local
245      keyring. */
246   struct akl
247   {
248     enum {
249       AKL_NODEFAULT,
250       AKL_LOCAL,
251       AKL_CERT,
252       AKL_PKA,
253       AKL_DANE,
254       AKL_LDAP,
255       AKL_KEYSERVER,
256       AKL_SPEC
257     } type;
258     keyserver_spec_t spec;
259     struct akl *next;
260   } *auto_key_locate;
261
262   int passphrase_repeat;
263   int pinentry_mode;
264 } opt;
265
266 /* CTRL is used to keep some global variables we currently can't
267    avoid.  Future concurrent versions of gpg will put it into a per
268    request structure CTRL. */
269 EXTERN_UNLESS_MAIN_MODULE
270 struct {
271   int in_auto_key_retrieve; /* True if we are doing an
272                                auto_key_retrieve. */
273   /* Hack to store the last error.  We currently need it because the
274      proc_packet machinery is not able to reliabale return error
275      codes.  Thus for the --server purposes we store some of the error
276      codes here.  FIXME! */
277   gpg_error_t lasterr;
278 } glo_ctrl;
279
280 #define DBG_PACKET_VALUE  1     /* debug packet reading/writing */
281 #define DBG_MPI_VALUE     2     /* debug mpi details */
282 #define DBG_CRYPTO_VALUE  4     /* debug crypto handling */
283                                 /* (may reveal sensitive data) */
284 #define DBG_FILTER_VALUE  8     /* debug internal filter handling */
285 #define DBG_IOBUF_VALUE   16    /* debug iobuf stuff */
286 #define DBG_MEMORY_VALUE  32    /* debug memory allocation stuff */
287 #define DBG_CACHE_VALUE   64    /* debug the caching */
288 #define DBG_MEMSTAT_VALUE 128   /* show memory statistics */
289 #define DBG_TRUST_VALUE   256   /* debug the trustdb */
290 #define DBG_HASHING_VALUE 512   /* debug hashing operations */
291 #define DBG_IPC_VALUE     1024  /* debug assuan communication */
292 #define DBG_CARD_IO_VALUE 2048  /* debug smart card I/O.  */
293 #define DBG_CLOCK_VALUE   4096
294 #define DBG_LOOKUP_VALUE  8192  /* debug the kety lookup */
295 #define DBG_EXTPROG_VALUE 16384 /* debug external program calls */
296
297 /* Tests for the debugging flags.  */
298 #define DBG_PACKET (opt.debug & DBG_PACKET_VALUE)
299 #define DBG_CRYPTO (opt.debug & DBG_CRYPTO_VALUE)
300 #define DBG_FILTER (opt.debug & DBG_FILTER_VALUE)
301 #define DBG_CACHE  (opt.debug & DBG_CACHE_VALUE)
302 #define DBG_TRUST  (opt.debug & DBG_TRUST_VALUE)
303 #define DBG_HASHING (opt.debug & DBG_HASHING_VALUE)
304 #define DBG_IPC     (opt.debug & DBG_IPC_VALUE)
305 #define DBG_CARD_IO (opt.debug & DBG_CARD_IO_VALUE)
306 #define DBG_IPC     (opt.debug & DBG_IPC_VALUE)
307 #define DBG_CLOCK   (opt.debug & DBG_CLOCK_VALUE)
308 #define DBG_LOOKUP  (opt.debug & DBG_LOOKUP_VALUE)
309 #define DBG_EXTPROG (opt.debug & DBG_EXTPROG_VALUE)
310
311 /* FIXME: We need to check whey we did not put this into opt. */
312 #define DBG_MEMORY    memory_debug_mode
313 #define DBG_MEMSTAT   memory_stat_debug_mode
314
315 EXTERN_UNLESS_MAIN_MODULE int memory_debug_mode;
316 EXTERN_UNLESS_MAIN_MODULE int memory_stat_debug_mode;
317
318
319 /* Compatibility flags.  */
320 #define GNUPG   (opt.compliance==CO_GNUPG)
321 #define RFC2440 (opt.compliance==CO_RFC2440)
322 #define RFC4880 (opt.compliance==CO_RFC4880)
323 #define PGP6    (opt.compliance==CO_PGP6)
324 #define PGP7    (opt.compliance==CO_PGP7)
325 #define PGP8    (opt.compliance==CO_PGP8)
326 #define PGPX    (PGP6 || PGP7 || PGP8)
327
328 /* Various option flags.  Note that there should be no common string
329    names between the IMPORT_ and EXPORT_ flags as they can be mixed in
330    the keyserver-options option. */
331
332 #define IMPORT_LOCAL_SIGS                (1<<0)
333 #define IMPORT_REPAIR_PKS_SUBKEY_BUG     (1<<1)
334 #define IMPORT_FAST                      (1<<2)
335 #define IMPORT_MERGE_ONLY                (1<<4)
336 #define IMPORT_MINIMAL                   (1<<5)
337 #define IMPORT_CLEAN                     (1<<6)
338 #define IMPORT_NO_SECKEY                 (1<<7)
339 #define IMPORT_KEEP_OWNERTTRUST          (1<<8)
340
341 #define EXPORT_LOCAL_SIGS                (1<<0)
342 #define EXPORT_ATTRIBUTES                (1<<1)
343 #define EXPORT_SENSITIVE_REVKEYS         (1<<2)
344 #define EXPORT_RESET_SUBKEY_PASSWD       (1<<3)
345 #define EXPORT_MINIMAL                   (1<<4)
346 #define EXPORT_CLEAN                     (1<<5)
347 #define EXPORT_DANE_FORMAT               (1<<6)
348
349 #define LIST_SHOW_PHOTOS                 (1<<0)
350 #define LIST_SHOW_POLICY_URLS            (1<<1)
351 #define LIST_SHOW_STD_NOTATIONS          (1<<2)
352 #define LIST_SHOW_USER_NOTATIONS         (1<<3)
353 #define LIST_SHOW_NOTATIONS (LIST_SHOW_STD_NOTATIONS|LIST_SHOW_USER_NOTATIONS)
354 #define LIST_SHOW_KEYSERVER_URLS         (1<<4)
355 #define LIST_SHOW_UID_VALIDITY           (1<<5)
356 #define LIST_SHOW_UNUSABLE_UIDS          (1<<6)
357 #define LIST_SHOW_UNUSABLE_SUBKEYS       (1<<7)
358 #define LIST_SHOW_KEYRING                (1<<8)
359 #define LIST_SHOW_SIG_EXPIRE             (1<<9)
360 #define LIST_SHOW_SIG_SUBPACKETS         (1<<10)
361 #define LIST_SHOW_USAGE                  (1<<11)
362
363 #define VERIFY_SHOW_PHOTOS               (1<<0)
364 #define VERIFY_SHOW_POLICY_URLS          (1<<1)
365 #define VERIFY_SHOW_STD_NOTATIONS        (1<<2)
366 #define VERIFY_SHOW_USER_NOTATIONS       (1<<3)
367 #define VERIFY_SHOW_NOTATIONS (VERIFY_SHOW_STD_NOTATIONS|VERIFY_SHOW_USER_NOTATIONS)
368 #define VERIFY_SHOW_KEYSERVER_URLS       (1<<4)
369 #define VERIFY_SHOW_UID_VALIDITY         (1<<5)
370 #define VERIFY_SHOW_UNUSABLE_UIDS        (1<<6)
371 #define VERIFY_PKA_LOOKUPS               (1<<7)
372 #define VERIFY_PKA_TRUST_INCREASE        (1<<8)
373 #define VERIFY_SHOW_PRIMARY_UID_ONLY     (1<<9)
374
375 #define KEYSERVER_HTTP_PROXY             (1<<0)
376 #define KEYSERVER_TIMEOUT                (1<<1)
377 #define KEYSERVER_ADD_FAKE_V3            (1<<2)
378 #define KEYSERVER_AUTO_KEY_RETRIEVE      (1<<3)
379 #define KEYSERVER_HONOR_KEYSERVER_URL    (1<<4)
380 #define KEYSERVER_HONOR_PKA_RECORD       (1<<5)
381
382
383 #endif /*G10_OPTIONS_H*/