1 /* agent.h - Global definitions for the agent
2 * Copyright (C) 2001, 2002, 2003, 2005, 2011 Free Software Foundation, Inc.
3 * Copyright (C) 2015 g10 Code GmbH.
5 * This file is part of GnuPG.
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.
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.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, see <https://www.gnu.org/licenses/>.
24 #ifdef GPG_ERR_SOURCE_DEFAULT
25 #error GPG_ERR_SOURCE_DEFAULT already defined
27 #define GPG_ERR_SOURCE_DEFAULT GPG_ERR_SOURCE_GPGAGENT
28 #include <gpg-error.h>
29 #define map_assuan_err(a) \
30 map_assuan_err_with_source (GPG_ERR_SOURCE_DEFAULT, (a))
34 #include "../common/util.h"
35 #include "../common/membuf.h"
36 #include "../common/sysutils.h" /* (gnupg_fd_t) */
37 #include "../common/session-env.h"
38 #include "../common/shareddefs.h"
40 /* To convey some special hash algorithms we use algorithm numbers
41 reserved for application use. */
42 #ifndef GCRY_MODULE_ID_USER
43 #define GCRY_MODULE_ID_USER 1024
45 #define MD_USER_TLS_MD5SHA1 (GCRY_MODULE_ID_USER+1)
47 /* Maximum length of a digest. */
48 #define MAX_DIGEST_LEN 64
50 /* The maximum length of a passphrase (in bytes). Note: this is
51 further contrained by the Assuan line length (and any other text on
52 the same line). However, the Assuan line length is 1k bytes so
53 this shouldn't be a problem in practice. */
54 #define MAX_PASSPHRASE_LEN 255
57 /* A large struct name "opt" to keep global flags */
60 unsigned int debug; /* Debug flags (DBG_foo_VALUE) */
61 int verbose; /* Verbosity level */
62 int quiet; /* Be as quiet as possible */
63 int dry_run; /* Don't change any persistent data */
64 int batch; /* Batch mode */
66 /* True if we handle sigusr2. */
69 /* Environment settings gathered at program start or changed using the
70 Assuan command UPDATESTARTUPTTY. */
71 session_env_t startup_env;
72 char *startup_lc_ctype;
73 char *startup_lc_messages;
75 /* Enable pinentry debugging (--debug 1024 should also be used). */
78 /* Filename of the program to start as pinentry. */
79 const char *pinentry_program;
81 /* Filename of the program to handle smartcard tasks. */
82 const char *scdaemon_program;
84 int disable_scdaemon; /* Never use the SCdaemon. */
86 int no_grab; /* Don't let the pinentry grab the keyboard */
88 /* The name of the file pinentry shall touch before exiting. If
89 this is not set the file name of the standard socket is used. */
90 const char *pinentry_touch_file;
92 /* A string where the first character is used by the pinentry as a
93 custom invisible character. */
94 char *pinentry_invisible_char;
96 /* The timeout value for the Pinentry in seconds. This is passed to
97 the pinentry if it is not 0. It is up to the pinentry to act
98 upon this timeout value. */
99 unsigned long pinentry_timeout;
101 /* The default and maximum TTL of cache entries. */
102 unsigned long def_cache_ttl; /* Default. */
103 unsigned long def_cache_ttl_ssh; /* for SSH. */
104 unsigned long max_cache_ttl; /* Default. */
105 unsigned long max_cache_ttl_ssh; /* for SSH. */
107 /* Flag disallowing bypassing of the warning. */
108 int enforce_passphrase_constraints;
110 /* The require minmum length of a passphrase. */
111 unsigned int min_passphrase_len;
113 /* The minimum number of non-alpha characters in a passphrase. */
114 unsigned int min_passphrase_nonalpha;
116 /* File name with a patternfile or NULL if not enabled. */
117 const char *check_passphrase_pattern;
119 /* If not 0 the user is asked to change his passphrase after these
121 unsigned int max_passphrase_days;
123 /* If set, a passphrase history will be written and checked at each
124 passphrase change. */
125 int enable_passphrase_history;
127 int running_detached; /* We are running detached from the tty. */
129 /* If this global option is true, the passphrase cache is ignored
130 for signing operations. */
131 int ignore_cache_for_signing;
133 /* If this global option is true, the user is allowed to
134 interactively mark certificate in trustlist.txt as trusted. */
135 int allow_mark_trusted;
137 /* If this global option is true, the Assuan command
138 PRESET_PASSPHRASE is allowed. */
139 int allow_preset_passphrase;
141 /* If this global option is true, the Assuan option
142 pinentry-mode=loopback is allowed. */
143 int allow_loopback_pinentry;
145 /* Allow the use of an external password cache. If this option is
146 enabled (which is the default) we send an option to Pinentry
147 to allow it to enable such a cache. */
148 int allow_external_cache;
150 /* If this global option is true, the Assuan option of Pinentry
151 allow-emacs-prompt is allowed. */
152 int allow_emacs_pinentry;
154 int keep_tty; /* Don't switch the TTY (for pinentry) on request */
155 int keep_display; /* Don't switch the DISPLAY (for pinentry) on request */
157 /* This global option indicates the use of an extra socket. Note
158 that we use a hack for cleanup handling in gpg-agent.c: If the
159 value is less than 2 the name has not yet been malloced. */
162 /* This global option indicates the use of an extra socket for web
163 browsers. Note that we use a hack for cleanup handling in
164 gpg-agent.c: If the value is less than 2 the name has not yet
170 /* Bit values for the --debug option. */
171 #define DBG_MPI_VALUE 2 /* debug mpi details */
172 #define DBG_CRYPTO_VALUE 4 /* debug low level crypto */
173 #define DBG_MEMORY_VALUE 32 /* debug memory allocation stuff */
174 #define DBG_CACHE_VALUE 64 /* debug the caching */
175 #define DBG_MEMSTAT_VALUE 128 /* show memory statistics */
176 #define DBG_HASHING_VALUE 512 /* debug hashing operations */
177 #define DBG_IPC_VALUE 1024 /* Enable Assuan debugging. */
179 /* Test macros for the debug option. */
180 #define DBG_CRYPTO (opt.debug & DBG_CRYPTO_VALUE)
181 #define DBG_MEMORY (opt.debug & DBG_MEMORY_VALUE)
182 #define DBG_CACHE (opt.debug & DBG_CACHE_VALUE)
183 #define DBG_HASHING (opt.debug & DBG_HASHING_VALUE)
184 #define DBG_IPC (opt.debug & DBG_IPC_VALUE)
186 /* Forward reference for local definitions in command.c. */
187 struct server_local_s;
189 /* Declaration of objects from command-ssh.c. */
190 struct ssh_control_file_s;
191 typedef struct ssh_control_file_s *ssh_control_file_t;
193 /* Forward reference for local definitions in call-scd.c. */
196 /* Collection of data per session (aka connection). */
197 struct server_control_s
199 /* Private data used to fire up the connection thread. We use this
200 structure do avoid an extra allocation for only a few bytes while
201 spawning a new connection thread. */
206 /* Flag indicating the connection is run in restricted mode.
207 A value of 1 if used for --extra-socket,
208 a value of 2 is used for --browser-socket. */
211 /* Private data of the server (command.c). */
212 struct server_local_s *server_local;
214 /* Private data of the SCdaemon (call-scd.c). */
215 struct scd_local_s *scd_local;
217 /* Environment settings for the connection. */
218 session_env_t session_env;
222 /* The current pinentry mode. */
223 pinentry_mode_t pinentry_mode;
225 /* The TTL used for the --preset option of certain commands. */
226 int cache_ttl_opt_preset;
228 /* Information on the currently used digest (for signing commands). */
231 unsigned char value[MAX_DIGEST_LEN];
235 unsigned char keygrip[20];
238 /* A flag to enable a hack to send the PKAUTH command instead of the
239 PKSIGN command to the scdaemon. */
242 /* A flag to inhibit enforced passphrase change during an explicit
246 /* The current S2K which might be different from the calibrated
248 unsigned long s2k_count;
252 /* Information pertaining to pinentry requests. */
253 struct pin_entry_info_s
255 int min_digits; /* min. number of digits required or 0 for freeform entry */
256 int max_digits; /* max. number of allowed digits allowed*/
257 int max_tries; /* max. number of allowed tries. */
258 int failed_tries; /* Number of tries so far failed. */
259 int with_qualitybar; /* Set if the quality bar should be displayed. */
260 int with_repeat; /* Request repetition of the passphrase. */
261 int repeat_okay; /* Repetition worked. */
262 gpg_error_t (*check_cb)(struct pin_entry_info_s *); /* CB used to check
264 void *check_cb_arg; /* optional argument which might be of use in the CB */
265 const char *cb_errtext; /* used by the cb to display a specific error */
266 size_t max_length; /* Allocated length of the buffer PIN. */
267 char pin[1]; /* The buffer to hold the PIN or passphrase.
268 It's actual allocated length is given by
269 MAX_LENGTH (above). */
273 /* Types of the private keys. */
276 PRIVATE_KEY_UNKNOWN = 0, /* Type of key is not known. */
277 PRIVATE_KEY_CLEAR = 1, /* The key is not protected. */
278 PRIVATE_KEY_PROTECTED = 2, /* The key is protected. */
279 PRIVATE_KEY_SHADOWED = 3, /* The key is a stub for a smartcard
281 PROTECTED_SHARED_SECRET = 4, /* RFU. */
282 PRIVATE_KEY_OPENPGP_NONE = 5 /* openpgp-native with protection "none". */
286 /* Values for the cache_mode arguments. */
289 CACHE_MODE_IGNORE = 0, /* Special mode to bypass the cache. */
290 CACHE_MODE_ANY, /* Any mode except ignore matches. */
291 CACHE_MODE_NORMAL, /* Normal cache (gpg-agent). */
292 CACHE_MODE_USER, /* GET_PASSPHRASE related cache. */
293 CACHE_MODE_SSH, /* SSH related cache. */
294 CACHE_MODE_NONCE /* This is a non-predictable nonce. */
298 /* The TTL is seconds used for adding a new nonce mode cache item. */
299 #define CACHE_TTL_NONCE 120
301 /* The TTL in seconds used by the --preset option of some commands.
302 This is the default value changeable by an OPTION command. */
303 #define CACHE_TTL_OPT_PRESET 900
306 /* The type of a function to lookup a TTL by a keygrip. */
307 typedef int (*lookup_ttl_t)(const char *hexgrip);
310 /* This is a special version of the usual _() gettext macro. It
311 assumes a server connection control variable with the name "ctrl"
312 and uses that to translate a string according to the locale set for
313 the connection. The macro LunderscoreIMPL is used by i18n to
314 actually define the inline function when needed. */
316 #define L_(a) agent_Lunderscore (ctrl, (a))
317 #define LunderscorePROTO \
318 static inline const char *agent_Lunderscore (ctrl_t ctrl, \
319 const char *string) \
320 GNUPG_GCC_ATTR_FORMAT_ARG(2);
321 #define LunderscoreIMPL \
322 static inline const char * \
323 agent_Lunderscore (ctrl_t ctrl, const char *string) \
325 return ctrl? i18n_localegettext (ctrl->lc_messages, string) \
326 /* */: gettext (string); \
333 /*-- gpg-agent.c --*/
334 void agent_exit (int rc)
335 GPGRT_ATTR_NORETURN; /* Also implemented in other tools */
336 void agent_set_progress_cb (void (*cb)(ctrl_t ctrl, const char *what,
337 int printchar, int current, int total),
339 gpg_error_t agent_copy_startup_env (ctrl_t ctrl);
340 const char *get_agent_socket_name (void);
341 const char *get_agent_ssh_socket_name (void);
342 int get_agent_active_connection_count (void);
343 #ifdef HAVE_W32_SYSTEM
344 void *get_agent_scd_notify_event (void);
346 void agent_sighup_action (void);
347 int map_pk_openpgp_to_gcry (int openpgp_algo);
348 void interrupt_main_thread_loop (void);
351 gpg_error_t agent_inq_pinentry_launched (ctrl_t ctrl, unsigned long pid,
353 gpg_error_t agent_write_status (ctrl_t ctrl, const char *keyword, ...)
354 GPGRT_ATTR_SENTINEL(0);
355 gpg_error_t agent_print_status (ctrl_t ctrl, const char *keyword,
356 const char *format, ...)
357 GPGRT_ATTR_PRINTF(3,4);
358 void bump_key_eventcounter (void);
359 void bump_card_eventcounter (void);
360 void start_command_handler (ctrl_t, gnupg_fd_t, gnupg_fd_t);
361 gpg_error_t pinentry_loopback (ctrl_t, const char *keyword,
362 unsigned char **buffer, size_t *size,
365 #ifdef HAVE_W32_SYSTEM
366 int serve_mmapped_ssh_request (ctrl_t ctrl,
367 unsigned char *request, size_t maxreqlen);
368 #endif /*HAVE_W32_SYSTEM*/
370 /*-- command-ssh.c --*/
371 ssh_control_file_t ssh_open_control_file (void);
372 void ssh_close_control_file (ssh_control_file_t cf);
373 gpg_error_t ssh_read_control_file (ssh_control_file_t cf,
374 char *r_hexgrip, int *r_disabled,
375 int *r_ttl, int *r_confirm);
376 gpg_error_t ssh_search_control_file (ssh_control_file_t cf,
379 int *r_ttl, int *r_confirm);
381 void start_command_handler_ssh (ctrl_t, gnupg_fd_t);
384 int agent_write_private_key (const unsigned char *grip,
385 const void *buffer, size_t length, int force);
386 gpg_error_t agent_key_from_file (ctrl_t ctrl,
387 const char *cache_nonce,
388 const char *desc_text,
389 const unsigned char *grip,
390 unsigned char **shadow_info,
391 cache_mode_t cache_mode,
392 lookup_ttl_t lookup_ttl,
394 char **r_passphrase);
395 gpg_error_t agent_raw_key_from_file (ctrl_t ctrl, const unsigned char *grip,
396 gcry_sexp_t *result);
397 gpg_error_t agent_public_key_from_file (ctrl_t ctrl,
398 const unsigned char *grip,
399 gcry_sexp_t *result);
400 int agent_is_dsa_key (gcry_sexp_t s_key);
401 int agent_is_eddsa_key (gcry_sexp_t s_key);
402 int agent_key_available (const unsigned char *grip);
403 gpg_error_t agent_key_info_from_file (ctrl_t ctrl, const unsigned char *grip,
405 unsigned char **r_shadow_info);
406 gpg_error_t agent_delete_key (ctrl_t ctrl, const char *desc_text,
407 const unsigned char *grip, int force);
409 /*-- call-pinentry.c --*/
410 void initialize_module_call_pinentry (void);
411 void agent_query_dump_state (void);
412 void agent_reset_query (ctrl_t ctrl);
413 int pinentry_active_p (ctrl_t ctrl, int waitseconds);
414 gpg_error_t agent_askpin (ctrl_t ctrl,
415 const char *desc_text, const char *prompt_text,
416 const char *inital_errtext,
417 struct pin_entry_info_s *pininfo,
418 const char *keyinfo, cache_mode_t cache_mode);
419 int agent_get_passphrase (ctrl_t ctrl, char **retpass,
420 const char *desc, const char *prompt,
421 const char *errtext, int with_qualitybar,
422 const char *keyinfo, cache_mode_t cache_mode);
423 int agent_get_confirmation (ctrl_t ctrl, const char *desc, const char *ok,
424 const char *notokay, int with_cancel);
425 int agent_show_message (ctrl_t ctrl, const char *desc, const char *ok_btn);
426 int agent_popup_message_start (ctrl_t ctrl,
427 const char *desc, const char *ok_btn);
428 void agent_popup_message_stop (ctrl_t ctrl);
429 int agent_clear_passphrase (ctrl_t ctrl,
430 const char *keyinfo, cache_mode_t cache_mode);
433 void initialize_module_cache (void);
434 void deinitialize_module_cache (void);
435 void agent_flush_cache (void);
436 int agent_put_cache (const char *key, cache_mode_t cache_mode,
437 const char *data, int ttl);
438 char *agent_get_cache (const char *key, cache_mode_t cache_mode);
439 void agent_store_cache_hit (const char *key);
443 int agent_pksign_do (ctrl_t ctrl, const char *cache_nonce,
444 const char *desc_text,
445 gcry_sexp_t *signature_sexp,
446 cache_mode_t cache_mode, lookup_ttl_t lookup_ttl,
447 const void *overridedata, size_t overridedatalen);
448 int agent_pksign (ctrl_t ctrl, const char *cache_nonce,
449 const char *desc_text,
450 membuf_t *outbuf, cache_mode_t cache_mode);
452 /*-- pkdecrypt.c --*/
453 int agent_pkdecrypt (ctrl_t ctrl, const char *desc_text,
454 const unsigned char *ciphertext, size_t ciphertextlen,
455 membuf_t *outbuf, int *r_padding);
458 int check_passphrase_constraints (ctrl_t ctrl, const char *pw,
459 char **failed_constraint);
460 gpg_error_t agent_ask_new_passphrase (ctrl_t ctrl, const char *prompt,
461 char **r_passphrase);
462 int agent_genkey (ctrl_t ctrl, const char *cache_nonce,
463 const char *keyparam, size_t keyparmlen,
464 int no_protection, const char *override_passphrase,
465 int preset, membuf_t *outbuf);
466 gpg_error_t agent_protect_and_store (ctrl_t ctrl, gcry_sexp_t s_skey,
467 char **passphrase_addr);
470 unsigned long get_standard_s2k_count (void);
471 unsigned char get_standard_s2k_count_rfc4880 (void);
472 int agent_protect (const unsigned char *plainkey, const char *passphrase,
473 unsigned char **result, size_t *resultlen,
474 unsigned long s2k_count, int use_ocb);
475 int agent_unprotect (ctrl_t ctrl,
476 const unsigned char *protectedkey, const char *passphrase,
477 gnupg_isotime_t protected_at,
478 unsigned char **result, size_t *resultlen);
479 int agent_private_key_type (const unsigned char *privatekey);
480 unsigned char *make_shadow_info (const char *serialno, const char *idstring);
481 int agent_shadow_key (const unsigned char *pubkey,
482 const unsigned char *shadow_info,
483 unsigned char **result);
484 int agent_get_shadow_info (const unsigned char *shadowkey,
485 unsigned char const **shadow_info);
486 gpg_error_t parse_shadow_info (const unsigned char *shadow_info,
487 char **r_hexsn, char **r_idstr, int *r_pinlen);
488 gpg_error_t s2k_hash_passphrase (const char *passphrase, int hashalgo,
490 const unsigned char *s2ksalt,
491 unsigned int s2kcount,
492 unsigned char *key, size_t keylen);
493 gpg_error_t agent_write_shadow_key (const unsigned char *grip,
494 const char *serialno, const char *keyid,
495 const unsigned char *pkbuf, int force);
498 /*-- trustlist.c --*/
499 void initialize_module_trustlist (void);
500 gpg_error_t agent_istrusted (ctrl_t ctrl, const char *fpr, int *r_disabled);
501 gpg_error_t agent_listtrusted (void *assuan_context);
502 gpg_error_t agent_marktrusted (ctrl_t ctrl, const char *name,
503 const char *fpr, int flag);
504 void agent_reload_trustlist (void);
507 /*-- divert-scd.c --*/
508 int divert_pksign (ctrl_t ctrl,
509 const unsigned char *digest, size_t digestlen, int algo,
510 const unsigned char *shadow_info, unsigned char **r_sig,
512 int divert_pkdecrypt (ctrl_t ctrl,
513 const unsigned char *cipher,
514 const unsigned char *shadow_info,
515 char **r_buf, size_t *r_len, int *r_padding);
516 int divert_generic_cmd (ctrl_t ctrl,
517 const char *cmdline, void *assuan_context);
518 int divert_writekey (ctrl_t ctrl, int force, const char *serialno,
519 const char *id, const char *keydata, size_t keydatalen);
523 void initialize_module_call_scd (void);
524 void agent_scd_dump_state (void);
525 int agent_scd_check_running (void);
526 void agent_scd_check_aliveness (void);
527 int agent_reset_scd (ctrl_t ctrl);
528 int agent_card_learn (ctrl_t ctrl,
529 void (*kpinfo_cb)(void*, const char *),
531 void (*certinfo_cb)(void*, const char *),
532 void *certinfo_cb_arg,
533 void (*sinfo_cb)(void*, const char *,
534 size_t, const char *),
536 int agent_card_serialno (ctrl_t ctrl, char **r_serialno, const char *demand);
537 int agent_card_pksign (ctrl_t ctrl,
539 int (*getpin_cb)(void *, const char *, char*, size_t),
542 const unsigned char *indata, size_t indatalen,
543 unsigned char **r_buf, size_t *r_buflen);
544 int agent_card_pkdecrypt (ctrl_t ctrl,
546 int (*getpin_cb)(void *, const char *, char*,size_t),
548 const unsigned char *indata, size_t indatalen,
549 char **r_buf, size_t *r_buflen, int *r_padding);
550 int agent_card_readcert (ctrl_t ctrl,
551 const char *id, char **r_buf, size_t *r_buflen);
552 int agent_card_readkey (ctrl_t ctrl, const char *id, unsigned char **r_buf);
553 int agent_card_writekey (ctrl_t ctrl, int force, const char *serialno,
554 const char *id, const char *keydata,
556 int (*getpin_cb)(void *, const char *, char*, size_t),
557 void *getpin_cb_arg);
558 gpg_error_t agent_card_getattr (ctrl_t ctrl, const char *name, char **result);
559 int agent_card_scd (ctrl_t ctrl, const char *cmdline,
560 int (*getpin_cb)(void *, const char *, char*, size_t),
561 void *getpin_cb_arg, void *assuan_context);
564 /*-- learncard.c --*/
565 int agent_handle_learn (ctrl_t ctrl, int send, void *assuan_context, int force);
568 /*-- cvt-openpgp.c --*/
570 extract_private_key (gcry_sexp_t s_key, int req_private_key_data,
571 const char **r_algoname, int *r_npkey, int *r_nskey,
572 const char **r_format,
573 gcry_mpi_t *mpi_array, int arraysize,
574 gcry_sexp_t *r_curve, gcry_sexp_t *r_flags);