Merge branch 'master' into npthnpth

Conflicts:
	ChangeLog-2011
	Makefile.am
	agent/ChangeLog-2011
	agent/gpg-agent.c
	dirmngr/ChangeLog-2011
	dirmngr/dirmngr.c
	doc/HACKING
	g13/g13.c
	po/de.po
	scd/ChangeLog-2011
	scd/apdu.c
	scd/command.c
	scd/scdaemon.c
	scripts/gitlog-to-changelog
	tools/ChangeLog-2011

6 files changed, 187 insertions, 85 deletions

diff --git a/agent/ChangeLog-2011 b/agent/ChangeLog-2011
index c074d1b65..f56be1f44 100644
--- a/agent/ChangeLog-2011
+++ b/agent/ChangeLog-2011
@@ -12,17 +12,6 @@
 	(ssh_handler_request_identities): Do not call card_key_available
 	if the scdaemon is disabled.
 
-2011-10-13  Marcus Brinkmann  <[email protected]>
-
-	* gpg-agent.c (start_connection_thread)
-	(start_connection_thread_ssh): Cast npth_self result to unsigned
-	long for safety.
-
-	* cache.c (new_data): Fix error check.
-
-	* cache.c, call-pinentry.c, call-scd.c, findkey.c, gpg-agent.c,
-	trustlist.c: Port to NPth.
-
 2011-09-12  Ben Kibbey <[email protected]>
 
 	* genkey.c (agent_ask_new_passphrase): Allow for an empty passphrase
diff --git a/agent/agent.h b/agent/agent.h
index b323718fc..4f4e477a6 100644
--- a/agent/agent.h
+++ b/agent/agent.h
@@ -73,17 +73,20 @@ struct
   /* True if we handle sigusr2.  */
   int sigusr2_enabled;
 
-  /* Environment setting gathered at program start or changed using the
+  /* Environment settings gathered at program start or changed using the
      Assuan command UPDATESTARTUPTTY. */
   session_env_t startup_env;
   char *startup_lc_ctype;
   char *startup_lc_messages;
 
-  const char *pinentry_program; /* Filename of the program to start as
-                                   pinentry.  */
-  const char *scdaemon_program; /* Filename of the program to handle
-                                   smartcard tasks.  */
+  /* Filename of the program to start as pinentry.  */
+  const char *pinentry_program;
+
+  /* Filename of the program to handle smartcard tasks.  */
+  const char *scdaemon_program;
+
   int disable_scdaemon;         /* Never use the SCdaemon. */
+
   int no_grab;         /* Don't let the pinentry grab the keyboard */
 
   /* The name of the file pinentry shall tocuh before exiting.  If
@@ -98,31 +101,51 @@ struct
 
   /* Flag disallowing bypassing of the warning.  */
   int enforce_passphrase_constraints;
+
   /* The require minmum length of a passphrase. */
   unsigned int min_passphrase_len;
+
   /* The minimum number of non-alpha characters in a passphrase.  */
   unsigned int min_passphrase_nonalpha;
+
   /* File name with a patternfile or NULL if not enabled.  */
   const char *check_passphrase_pattern;
+
   /* If not 0 the user is asked to change his passphrase after these
      number of days.  */
   unsigned int max_passphrase_days;
+
   /* If set, a passphrase history will be written and checked at each
      passphrase change.  */
   int enable_passhrase_history;
 
   int running_detached; /* We are running detached from the tty. */
 
+  /* If this global option is true, the passphrase cache is ignored
+     for signing operations.  */
   int ignore_cache_for_signing;
+
+  /* If this global option is true, the user is allowed to
+     interactively mark certificate in trustlist.txt as trusted. */
   int allow_mark_trusted;
+
+  /* If this global option is true, the Assuan command
+     PRESET_PASSPHRASE is allowed.  */
   int allow_preset_passphrase;
+
+  /* If this global option is true, the Assuan option
+     pinentry-mode=loopback is allowed.  */
   int allow_loopback_pinentry;
+
   int keep_tty;      /* Don't switch the TTY (for pinentry) on request */
   int keep_display;  /* Don't switch the DISPLAY (for pinentry) on request */
-  int ssh_support;   /* Enable ssh-agent emulation.  */
+
+  /* This global option enables the ssh-agent subsystem.  */
+  int ssh_support;
 } opt;
 
 
+/* Bit values for the --debug option.  */
 #define DBG_COMMAND_VALUE 1	/* debug commands i/o */
 #define DBG_MPI_VALUE	  2	/* debug mpi details */
 #define DBG_CRYPTO_VALUE  4	/* debug low level crypto */
@@ -130,8 +153,9 @@ struct
 #define DBG_CACHE_VALUE   64	/* debug the caching */
 #define DBG_MEMSTAT_VALUE 128	/* show memory statistics */
 #define DBG_HASHING_VALUE 512	/* debug hashing operations */
-#define DBG_ASSUAN_VALUE 1024
+#define DBG_ASSUAN_VALUE 1024   /* Enable Assuan debugging.  */
 
+/* Test macros for the debug option.  */
 #define DBG_COMMAND (opt.debug & DBG_COMMAND_VALUE)
 #define DBG_CRYPTO  (opt.debug & DBG_CRYPTO_VALUE)
 #define DBG_MEMORY  (opt.debug & DBG_MEMORY_VALUE)
@@ -139,14 +163,18 @@ struct
 #define DBG_HASHING (opt.debug & DBG_HASHING_VALUE)
 #define DBG_ASSUAN  (opt.debug & DBG_ASSUAN_VALUE)
 
+/* Forward reference for local definitions in command.c.  */
 struct server_local_s;
+
+/* Forward reference for local definitions in call-scd.c.  */
 struct scd_local_s;
 
 /* Collection of data per session (aka connection). */
 struct server_control_s
 {
   /* Private data used to fire up the connection thread.  We use this
-     structure do avoid an extra allocation for just a few bytes. */
+     structure do avoid an extra allocation for only a few bytes while
+     spawning a new connection thread.  */
   struct {
     gnupg_fd_t fd;
   } thread_startup;
@@ -157,6 +185,7 @@ struct server_control_s
   /* Private data of the SCdaemon (call-scd.c). */
   struct scd_local_s *scd_local;
 
+  /* Environment settings for the connection.  */
   session_env_t session_env;
   char *lc_ctype;
   char *lc_messages;
@@ -177,37 +206,47 @@ struct server_control_s
   unsigned char keygrip[20];
   int have_keygrip;
 
-  int use_auth_call; /* Hack to send the PKAUTH command instead of the
-                        PKSIGN command to the scdaemon.  */
-  int in_passwd;     /* Hack to inhibit enforced passphrase change
-                        during an explicit passwd command.  */
+  /* A flag to enable a hack to send the PKAUTH command instead of the
+     PKSIGN command to the scdaemon.  */
+  int use_auth_call;
+
+  /* A flag to inhibit enforced passphrase change during an explicit
+     passwd command.  */
+  int in_passwd;
 
-  unsigned long s2k_count; /* Other than the calibrated count. */
+  /* The current S2K which might be different from the calibrated
+     count. */
+  unsigned long s2k_count;
 };
 
 
+/* Information pertaining to pinentry requests.  */
 struct pin_entry_info_s
 {
   int min_digits; /* min. number of digits required or 0 for freeform entry */
   int max_digits; /* max. number of allowed digits allowed*/
-  int max_tries;
-  int failed_tries;
+  int max_tries;  /* max. number of allowed tries.  */
+  int failed_tries; /* Number of tries so far failed.  */
   int with_qualitybar; /* Set if the quality bar should be displayed.  */
   int (*check_cb)(struct pin_entry_info_s *); /* CB used to check the PIN */
   void *check_cb_arg;  /* optional argument which might be of use in the CB */
   const char *cb_errtext; /* used by the cb to display a specific error */
-  size_t max_length;      /* allocated length of the buffer */
-  char pin[1];
+  size_t max_length;   /* Allocated length of the buffer PIN. */
+  char pin[1];         /* The buffer to hold the PIN or passphrase.
+                          It's actual allocated length is given by
+                          MAX_LENGTH (above).  */
 };
 
 
+/* Types of the private keys.  */
 enum
   {
-    PRIVATE_KEY_UNKNOWN = 0,
-    PRIVATE_KEY_CLEAR = 1,
-    PRIVATE_KEY_PROTECTED = 2,
-    PRIVATE_KEY_SHADOWED = 3,
-    PROTECTED_SHARED_SECRET = 4
+    PRIVATE_KEY_UNKNOWN = 0,      /* Type of key is not known.  */
+    PRIVATE_KEY_CLEAR = 1,        /* The key is not protected.  */
+    PRIVATE_KEY_PROTECTED = 2,    /* The key is protected.  */
+    PRIVATE_KEY_SHADOWED = 3,     /* The key is a stub for a smartcard
+                                     based key.  */
+    PROTECTED_SHARED_SECRET = 4   /* RFU.  */
   };
 
 
diff --git a/agent/call-pinentry.c b/agent/call-pinentry.c
index f5dc1aaa9..34ab3840e 100644
--- a/agent/call-pinentry.c
+++ b/agent/call-pinentry.c
@@ -1261,8 +1261,7 @@ agent_popup_message_stop (ctrl_t ctrl)
         assuan_set_flag (entry_ctx, ASSUAN_NO_WAITPID, 1);
     }
   else if (pid > 0)
-    kill (pid, SIGKILL);  /* Need to use SIGKILL due to bad
-                             interaction of SIGINT with Pth. */
+    kill (pid, SIGINT);
 #endif
 
   /* Now wait for the thread to terminate. */
diff --git a/agent/call-scd.c b/agent/call-scd.c
index f61858e5f..8a6c8ba68 100644
--- a/agent/call-scd.c
+++ b/agent/call-scd.c
@@ -1,5 +1,6 @@
 /* call-scd.c - fork of the scdaemon to do SC operations
- * Copyright (C) 2001, 2002, 2005, 2007, 2010 Free Software Foundation, Inc.
+ * Copyright (C) 2001, 2002, 2005, 2007, 2010,
+ *               2011 Free Software Foundation, Inc.
  *
  * This file is part of GnuPG.
  *
@@ -44,15 +45,6 @@
 #define MAX_OPEN_FDS 20
 #endif
 
-/* This Assuan flag is only available since libassuan 2.0.2.  Because
-   comments lines are comments anyway we can use a replacement which
-   might not do anything.  assuan_{g,s}et_flag don't return an error
-   thus there won't be any ABI problem.  */
-#ifndef ASSUAN_CONVEY_COMMENTS
-#define ASSUAN_CONVEY_COMMENTS 4
-#endif
-
-
 /* Definition of module local data of the CTRL structure.  */
 struct scd_local_s
 {
@@ -1115,16 +1107,28 @@ pass_status_thru (void *opaque, const char *line)
   char keyword[200];
   int i;
 
-  for (i=0; *line && !spacep (line) && i < DIM(keyword)-1; line++, i++)
-    keyword[i] = *line;
-  keyword[i] = 0;
-  /* truncate any remaining keyword stuff. */
-  for (; *line && !spacep (line); line++)
-    ;
-  while (spacep (line))
-    line++;
+  if (line[0] == '#' && (!line[1] || spacep (line+1)))
+    {
+      /* We are called in convey comments mode.  Now, if we see a
+         comment marker as keyword we forward the line verbatim to the
+         the caller.  This way the comment lines from scdaemon won't
+         appear as status lines with keyword '#'.  */
+      assuan_write_line (ctx, line);
+    }
+  else
+    {
+      for (i=0; *line && !spacep (line) && i < DIM(keyword)-1; line++, i++)
+        keyword[i] = *line;
+      keyword[i] = 0;
 
-  assuan_write_status (ctx, keyword, line);
+      /* Truncate any remaining keyword stuff.  */
+      for (; *line && !spacep (line); line++)
+        ;
+      while (spacep (line))
+        line++;
+
+      assuan_write_status (ctx, keyword, line);
+    }
   return 0;
 }
 
diff --git a/agent/command.c b/agent/command.c
index f310a980c..ad86a3575 100644
--- a/agent/command.c
+++ b/agent/command.c
@@ -50,31 +50,57 @@
 /* The size of the import/export KEK key (in bytes).  */
 #define KEYWRAP_KEYSIZE (128/8)
 
+/* A shortcut to call assuan_set_error using an gpg_err_code_t and a
+   text string.  */
 #define set_error(e,t) assuan_set_error (ctx, gpg_error (e), (t))
 
-
+/* Check that the maximum digest length we support has at least the
+   length of the keygrip.  */
 #if MAX_DIGEST_LEN < 20
 #error MAX_DIGEST_LEN shorter than keygrip
 #endif
 
-/* Data used to associate an Assuan context with local server data */
+/* Data used to associate an Assuan context with local server data.
+   This is this modules local part of the server_control_s struct.  */
 struct server_local_s
 {
+  /* Our Assuan context.  */
   assuan_context_t assuan_ctx;
-  int message_fd;
+
+  /* If this flag is true, the passphrase cache is used for signing
+     operations.  It defaults to true but may be set on a per
+     connection base.  The global option opt.ignore_cache_for_signing
+     takes precedence over this flag.  */
   int use_cache_for_signing;
-  char *keydesc;  /* Allocated description for the next key
-                     operation. */
-  int pause_io_logging; /* Used to suppress I/O logging during a command */
-  int stopme;    /* If set to true the agent will be terminated after
-                    the end of this session.  */
-  int allow_pinentry_notify; /* Set if pinentry notifications should
-                                be done. */
-  void *import_key;  /* Malloced KEK for the import_key command.  */
-  void *export_key;  /* Malloced KEK for the export_key command.  */
-  int allow_fully_canceled; /* Client is aware of GPG_ERR_FULLY_CANCELED.  */
-  char *last_cache_nonce;   /* Last CACHE_NOCNE sent as status (malloced).  */
-  char *last_passwd_nonce;  /* Last PASSWD_NOCNE sent as status (malloced). */
+
+  /* An allocated description for the next key operation.  This is
+     used if a pinnetry needs to be popped up.  */
+  char *keydesc;
+
+  /* Flags to suppress I/O logging during a command.  */
+  int pause_io_logging;
+
+  /* If this flags is set to true the agent will be terminated after
+     the end of the current session.  */
+  int stopme;
+
+  /* Flag indicating whether pinentry notifications shall be done. */
+  int allow_pinentry_notify;
+
+  /* Malloced KEK (Key-Encryption-Key) for the import_key command.  */
+  void *import_key;
+
+  /* Malloced KEK for the export_key command.  */
+  void *export_key;
+
+  /* Client is aware of the error code GPG_ERR_FULLY_CANCELED.  */
+  int allow_fully_canceled;
+
+  /* Last CACHE_NONCE sent as status (malloced).  */
+  char *last_cache_nonce;
+
+  /* Last PASSWD_NONCE sent as status (malloced). */
+  char *last_passwd_nonce;
 };
 
 
@@ -156,6 +182,8 @@ write_and_clear_outbuf (assuan_context_t ctx, membuf_t *mb)
 }
 
 
+/* Clear the nonces used to enable the passphrase cache for certain
+   multi-command command sequences.  */
 static void
 clear_nonce_cache (ctrl_t ctrl)
 {
@@ -176,6 +204,9 @@ clear_nonce_cache (ctrl_t ctrl)
 }
 
 
+/* This function is called by Libassuan whenever thee client sends a
+   reset.  It has been registered similar to the other Assuan
+   commands.  */
 static gpg_error_t
 reset_notify (assuan_context_t ctx, char *line)
 {
@@ -196,8 +227,13 @@ reset_notify (assuan_context_t ctx, char *line)
 }
 
 
-/* Skip over options.
-   Blanks after the options are also removed. */
+/* Skip over options in LINE.
+
+   Blanks after the options are also removed.  Options are indicated
+   by two leading dashes followed by a string consisting of non-space
+   characters.  The special option "--" indicates an explicit end of
+   options; all what follows will not be considered an option.  The
+   first no-option string also indicates the end of option parsing. */
 static char *
 skip_options (const char *line)
 {
@@ -213,7 +249,11 @@ skip_options (const char *line)
   return (char*)line;
 }
 
-/* Check whether the option NAME appears in LINE */
+
+/* Check whether the option NAME appears in LINE.  An example for a
+   line with options is:
+     --algo=42 --data foo bar
+   This function would then only return true if NAME is "data".  */
 static int
 has_option (const char *line, const char *name)
 {
@@ -226,6 +266,7 @@ has_option (const char *line, const char *name)
   return (s && (s == line || spacep (s-1)) && (!s[n] || spacep (s+n)));
 }
 
+
 /* Same as has_option but does only test for the name of the option
    and ignores an argument, i.e. with NAME being "--hash" it would
    return true for "--hash" as well as for "--hash=foo". */
@@ -242,8 +283,9 @@ has_option_name (const char *line, const char *name)
           && (!s[n] || spacep (s+n) || s[n] == '='));
 }
 
+
 /* Return a pointer to the argument of the option with NAME.  If such
-   an option is not given, it returns NULL. */
+   an option is not given, NULL is retruned. */
 static char *
 option_value (const char *line, const char *name)
 {
@@ -265,7 +307,7 @@ option_value (const char *line, const char *name)
 }
 
 
-/* Replace all '+' by a blank. */
+/* Replace all '+' by a blank in the string S. */
 static void
 plus_to_blank (char *s)
 {
@@ -296,8 +338,9 @@ parse_hexstring (assuan_context_t ctx, const char *string, size_t *len)
   return 0;
 }
 
+
 /* Parse the keygrip in STRING into the provided buffer BUF.  BUF must
-   provide space for 20 bytes. BUF is not changed if the function
+   provide space for 20 bytes.  BUF is not changed if the function
    returns an error. */
 static int
 parse_keygrip (assuan_context_t ctx, const char *string, unsigned char *buf)
@@ -319,7 +362,11 @@ parse_keygrip (assuan_context_t ctx, const char *string, unsigned char *buf)
 }
 
 
-/* Write an assuan status line. */
+/* Write an Assuan status line.  KEYWORD is the first item on the
+   status line.  The following arguments are all separated by a space
+   in the output.  The last argument must be a NULL.  Linefeeds and
+   carriage returns characters (which are not allowed in an Assuan
+   status line) are silently quoted in C-style.  */
 gpg_error_t
 agent_write_status (ctrl_t ctrl, const char *keyword, ...)
 {
@@ -463,6 +510,7 @@ bump_key_eventcounter (void)
   eventcounter.any++;
 }
 
+
 /* This function should be called for all card reader status
    changes.  This function is assured not to do any context
    switches. */
@@ -1069,6 +1117,8 @@ do_one_keyinfo (ctrl_t ctrl, const unsigned char *grip, assuan_context_t ctx,
 }
 
 
+/* Entry int for the command KEYINFO.  This function handles the
+   command option processing.  For details see hlp_keyinfo above.  */
 static gpg_error_t
 cmd_keyinfo (assuan_context_t ctx, char *line)
 {
@@ -1140,6 +1190,7 @@ cmd_keyinfo (assuan_context_t ctx, char *line)
 
 
 
+/* Helper for cmd_get_passphrase.  */
 static int
 send_back_passphrase (assuan_context_t ctx, int via_data, const char *pw)
 {
@@ -2259,12 +2310,8 @@ cmd_killagent (assuan_context_t ctx, char *line)
     return set_error (GPG_ERR_NOT_SUPPORTED, "no --use-standard-socket");
 
   ctrl->server_local->stopme = 1;
-#ifdef ASSUAN_FORCE_CLOSE
   assuan_set_flag (ctx, ASSUAN_FORCE_CLOSE, 1);
   return 0;
-#else
-  return gpg_error (GPG_ERR_EOF);
-#endif
 }
 
 
@@ -2415,6 +2462,8 @@ cmd_getinfo (assuan_context_t ctx, char *line)
 
 
 
+/* This function is called by Libassuan to parse the OPTION command.
+   It has been registered similar to the other Assuan commands.  */
 static gpg_error_t
 option_handler (assuan_context_t ctx, const char *key, const char *value)
 {
@@ -2574,7 +2623,8 @@ command_has_option (const char *cmd, const char *cmdopt)
 }
 
 
-/* Tell the assuan library about our commands */
+/* Tell Libassuan about our commands.  Also register the other Assuan
+   handlers. */
 static int
 register_commands (assuan_context_t ctx)
 {
@@ -2685,7 +2735,6 @@ start_command_handler (ctrl_t ctrl, gnupg_fd_t listen_fd, gnupg_fd_t fd)
   assuan_set_pointer (ctx, ctrl);
   ctrl->server_local = xcalloc (1, sizeof *ctrl->server_local);
   ctrl->server_local->assuan_ctx = ctx;
-  ctrl->server_local->message_fd = -1;
   ctrl->server_local->use_cache_for_signing = 1;
   ctrl->digest.raw_value = 0;
 
@@ -2733,6 +2782,8 @@ start_command_handler (ctrl_t ctrl, gnupg_fd_t listen_fd, gnupg_fd_t fd)
 }
 
 
+/* Helper for the pinentry loopback mode.  It merely passes the
+   parameters on to the client.  */
 gpg_error_t
 pinentry_loopback(ctrl_t ctrl, const char *keyword,
                   unsigned char **buffer, size_t *size,
diff --git a/agent/gpg-agent.c b/agent/gpg-agent.c
index 53d25402a..f741f052c 100644
--- a/agent/gpg-agent.c
+++ b/agent/gpg-agent.c
@@ -299,6 +299,9 @@ ASSUAN_SYSTEM_NPTH_IMPL;
    Functions.
  */
 
+/* Allocate a string describing a library version by calling a GETFNC.
+   This function is expected to be called only once.  GETFNC is
+   expected to have a semantic like gcry_check_version ().  */
 static char *
 make_libversion (const char *libname, const char *(*getfnc)(const char*))
 {
@@ -316,7 +319,9 @@ make_libversion (const char *libname, const char *(*getfnc)(const char*))
   return result;
 }
 
-
+/* Return strings describing this program.  The case values are
+   described in common/argparse.c:strusage.  The values here override
+   the default values given by strusage.  */
 static const char *
 my_strusage (int level)
 {
@@ -438,6 +443,9 @@ remove_socket (char *name)
     }
 }
 
+
+/* Cleanup code for this program.  This is either called has an atexit
+   handler or directly.  */
 static void
 cleanup (void)
 {
@@ -1150,11 +1158,11 @@ main (int argc, char **argv )
               if (csh_style)
                 {
                   *strchr (infostr, '=') = ' ';
-                  es_printf ("setenv %s\n", infostr);
+                  es_printf ("setenv %s;\n", infostr);
 		  if (opt.ssh_support)
 		    {
 		      *strchr (infostr_ssh_sock, '=') = ' ';
-		      es_printf ("setenv %s\n", infostr_ssh_sock);
+		      es_printf ("setenv %s;\n", infostr_ssh_sock);
 		    }
                 }
               else
@@ -1238,6 +1246,8 @@ main (int argc, char **argv )
 }
 
 
+/* Exit entry point.  This function should be called instead of a
+   plain exit.  */
 void
 agent_exit (int rc)
 {
@@ -1264,6 +1274,11 @@ agent_exit (int rc)
 }
 
 
+/* Each thread has its own local variables conveyed by a control
+   structure usually identified by an argument named CTRL.  This
+   function is called immediately after allocating the control
+   structure.  Its purpose is to setup the default values for that
+   structure.  */
 static void
 agent_init_default_ctrl (ctrl_t ctrl)
 {
@@ -1289,6 +1304,8 @@ agent_init_default_ctrl (ctrl_t ctrl)
 }
 
 
+/* Release all resources allocated by default in the control
+   structure.  This is the counterpart to agent_init_default_ctrl.  */
 static void
 agent_deinit_default_ctrl (ctrl_t ctrl)
 {
@@ -1690,6 +1707,7 @@ agent_sighup_action (void)
 }
 
 
+/* A helper function to handle SIGUSR2.  */
 static void
 agent_sigusr2_action (void)
 {
@@ -1700,6 +1718,8 @@ agent_sigusr2_action (void)
 }
 
 
+/* The signal handler for this program.  It is expected to be run in
+   its own trhead and not in the context of a signal handler.  */
 static void
 handle_signal (int signo)
 {