gpgv,w32: Fix --status-fd.
[gnupg.git] / g10 / getkey.c
index b09d967..163ab80 100644 (file)
@@ -1,7 +1,7 @@
 /* getkey.c -  Get a key from the database
  * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
  *               2007, 2008, 2010  Free Software Foundation, Inc.
- * Copyright (C) 2015 g10 Code GmbH
+ * Copyright (C) 2015, 2016 g10 Code GmbH
  *
  * This file is part of GnuPG.
  *
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ * along with this program; if not, see <https://www.gnu.org/licenses/>.
  */
 
 #include <config.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
-#include <assert.h>
 #include <ctype.h>
 
 #include "gpg.h"
@@ -39,6 +38,7 @@
 #include "call-agent.h"
 #include "host2net.h"
 #include "mbox-util.h"
+#include "status.h"
 
 #define MAX_PK_CACHE_ENTRIES   PK_UID_CACHE_SIZE
 #define MAX_UID_CACHE_ENTRIES  PK_UID_CACHE_SIZE
 #error We need the cache for key creation
 #endif
 
+/* Flags values returned by the lookup code.  Note that the values are
+ * directly used by the KEY_CONSIDERED status line.  */
+#define LOOKUP_NOT_SELECTED        (1<<0)
+#define LOOKUP_ALL_SUBKEYS_EXPIRED (1<<1)  /* or revoked */
+
+
+/* A context object used by the lookup functions.  */
 struct getkey_ctx_s
 {
   /* Part of the search criteria: whether the search is an exact
@@ -136,6 +143,11 @@ static void merge_selfsigs (kbnode_t keyblock);
 static int lookup (getkey_ctx_t ctx,
                   kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
                   int want_secret);
+static kbnode_t finish_lookup (kbnode_t keyblock,
+                               unsigned int req_usage, int want_exact,
+                               unsigned int *r_flags);
+static void print_status_key_considered (kbnode_t keyblock, unsigned int flags);
+
 
 #if 0
 static void
@@ -155,7 +167,18 @@ print_stats ()
 #endif
 
 
-/* For documentation see keydb.h.  */
+/* Cache a copy of a public key in the public key cache.  PK is not
+ * cached if caching is disabled (via getkey_disable_caches), if
+ * PK->FLAGS.DONT_CACHE is set, we don't know how to derive a key id
+ * from the public key (e.g., unsupported algorithm), or a key with
+ * the key id is already in the cache.
+ *
+ * The public key packet is copied into the cache using
+ * copy_public_key.  Thus, any secret parts are not copied, for
+ * instance.
+ *
+ * This cache is filled by get_pubkey and is read by get_pubkey and
+ * get_pubkey_fast.  */
 void
 cache_public_key (PKT_public_key * pk)
 {
@@ -196,7 +219,7 @@ cache_public_key (PKT_public_key * pk)
       /* Remove the last 50% of the entries.  */
       for (ce = pk_cache, n = 0; ce && n < pk_cache_entries/2; n++)
         ce = ce->next;
-      if (ce != pk_cache && ce->next)
+      if (ce && ce != pk_cache && ce->next)
         {
           ce2 = ce->next;
           ce->next = NULL;
@@ -209,7 +232,7 @@ cache_public_key (PKT_public_key * pk)
               pk_cache_entries--;
             }
         }
-      assert (pk_cache_entries < MAX_PK_CACHE_ENTRIES);
+      log_assert (pk_cache_entries < MAX_PK_CACHE_ENTRIES);
     }
   pk_cache_entries++;
   ce = xmalloc (sizeof *ce);
@@ -300,7 +323,8 @@ cache_user_id (KBNODE keyblock)
          /* First check for duplicates.  */
          for (r = user_id_db; r; r = r->next)
            {
-             keyid_list_t b = r->keyids;
+             keyid_list_t b;
+
              for (b = r->keyids; b; b = b->next)
                {
                  if (!memcmp (b->fpr, a->fpr, MAX_FINGERPRINT_LEN))
@@ -343,7 +367,9 @@ cache_user_id (KBNODE keyblock)
 }
 
 
-/* For documentation see keydb.h.  */
+/* Disable and drop the public key cache (which is filled by
+   cache_public_key and get_pubkey).  Note: there is currently no way
+   to reenable this cache.  */
 void
 getkey_disable_caches ()
 {
@@ -366,22 +392,310 @@ getkey_disable_caches ()
 }
 
 
-static void
-pk_from_block (GETKEY_CTX ctx, PKT_public_key * pk, KBNODE keyblock,
-              KBNODE found_key)
+void
+pubkey_free (pubkey_t key)
+{
+  if (key)
+    {
+      xfree (key->pk);
+      release_kbnode (key->keyblock);
+      xfree (key);
+    }
+}
+
+void
+pubkeys_free (pubkey_t keys)
 {
-  KBNODE a = found_key ? found_key : keyblock;
+  while (keys)
+    {
+      pubkey_t next = keys->next;
+      pubkey_free (keys);
+      keys = next;
+    }
+}
+
+/* Returns all keys that match the search specfication SEARCH_TERMS.
+
+   This function also checks for and warns about duplicate entries in
+   the keydb, which can occur if the user has configured multiple
+   keyrings or keyboxes or if a keyring or keybox was corrupted.
+
+   Note: SEARCH_TERMS will not be expanded (i.e., it may not be a
+   group).
+
+   USE is the operation for which the key is required.  It must be
+   either PUBKEY_USAGE_ENC, PUBKEY_USAGE_SIG, PUBKEY_USAGE_CERT or
+   PUBKEY_USAGE_AUTH.
+
+   XXX: Currently, only PUBKEY_USAGE_ENC and PUBKEY_USAGE_SIG are
+   implemented.
+
+   INCLUDE_UNUSABLE indicates whether disabled keys are allowed.
+   (Recipients specified with --encrypt-to and --hidden-encrypt-to may
+   be disabled.  It is possible to edit disabled keys.)
+
+   SOURCE is the context in which SEARCH_TERMS was specified, e.g.,
+   "--encrypt-to", etc.  If this function is called interactively,
+   then this should be NULL.
+
+   If WARN_POSSIBLY_AMBIGUOUS is set, then emits a warning if the user
+   does not specify a long key id or a fingerprint.
+
+   The results are placed in *KEYS.  *KEYS must be NULL!  */
+gpg_error_t
+get_pubkeys (ctrl_t ctrl,
+             char *search_terms, int use, int include_unusable, char *source,
+             int warn_possibly_ambiguous,
+             pubkey_t *r_keys)
+{
+  /* We show a warning when a key appears multiple times in the DB.
+     This can happen for two reasons:
+
+       - The user has configured multiple keyrings or keyboxes.
+
+       - The keyring or keybox has been corrupted in some way, e.g., a
+         bug or a random process changing them.
+
+     For each duplicate, we only want to show the key once.  Hence,
+     this list.  */
+  static strlist_t key_dups;
+
+  /* USE transformed to a string.  */
+  char *use_str;
+
+  gpg_error_t err;
+
+  KEYDB_SEARCH_DESC desc;
+
+  GETKEY_CTX ctx;
+  pubkey_t results = NULL;
+  pubkey_t r;
+
+  int count;
+
+  char fingerprint[2 * MAX_FINGERPRINT_LEN + 1];
+
+  if (DBG_LOOKUP)
+    {
+      log_debug ("\n");
+      log_debug ("%s: Checking %s=%s\n",
+                 __func__, source ? source : "user input", search_terms);
+    }
+
+  if (*r_keys)
+    log_bug ("%s: KEYS should be NULL!\n", __func__);
+
+  switch (use)
+    {
+    case PUBKEY_USAGE_ENC: use_str = "encrypt"; break;
+    case PUBKEY_USAGE_SIG: use_str = "sign"; break;
+    case PUBKEY_USAGE_CERT: use_str = "cetify"; break;
+    case PUBKEY_USAGE_AUTH: use_str = "authentication"; break;
+    default: log_bug ("%s: Bad value for USE (%d)\n", __func__, use);
+    }
+
+  if (use == PUBKEY_USAGE_CERT || use == PUBKEY_USAGE_AUTH)
+    log_bug ("%s: use=%s is unimplemented.\n", __func__, use_str);
+
+  err = classify_user_id (search_terms, &desc, 1);
+  if (err)
+    {
+      log_info (_("key \"%s\" not found: %s\n"),
+                search_terms, gpg_strerror (err));
+      if (!opt.quiet && source)
+        log_info (_("(check argument of option '%s')\n"), source);
+      goto out;
+    }
+
+  if (warn_possibly_ambiguous
+      && ! (desc.mode == KEYDB_SEARCH_MODE_LONG_KID
+            || desc.mode == KEYDB_SEARCH_MODE_FPR16
+            || desc.mode == KEYDB_SEARCH_MODE_FPR20
+            || desc.mode == KEYDB_SEARCH_MODE_FPR))
+    {
+      log_info (_("Warning: '%s' should be a long key ID or a fingerprint\n"),
+                search_terms);
+      if (!opt.quiet && source)
+        log_info (_("(check argument of option '%s')\n"), source);
+    }
+
+  /* Gather all of the results.  */
+  ctx = NULL;
+  count = 0;
+  do
+    {
+      PKT_public_key *pk = xmalloc_clear (sizeof *pk);
+      KBNODE kb;
+      pk->req_usage = use;
+
+      if (! ctx)
+        err = get_pubkey_byname (ctrl, &ctx, pk, search_terms, &kb, NULL,
+                                 include_unusable, 1);
+      else
+        err = getkey_next (ctx, pk, &kb);
+
+      if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
+        /* No more results.   */
+        {
+          xfree (pk);
+          break;
+        }
+      else if (err)
+        /* An error (other than "not found").  */
+        {
+          log_error (_("error looking up: %s\n"),
+                     gpg_strerror (err));
+          xfree (pk);
+          break;
+        }
+
+      /* Another result!  */
+      count ++;
+
+      r = xmalloc_clear (sizeof (*r));
+      r->pk = pk;
+      r->keyblock = kb;
+      r->next = results;
+      results = r;
+    }
+  while (ctx);
+  getkey_end (ctx);
+
+  if (DBG_LOOKUP)
+    {
+      log_debug ("%s resulted in %d matches.\n", search_terms, count);
+      for (r = results; r; r = r->next)
+        log_debug ("  %s\n",
+                   hexfingerprint (r->keyblock->pkt->pkt.public_key,
+                                   fingerprint, sizeof (fingerprint)));
+    }
+
+  if (! results && gpg_err_code (err) == GPG_ERR_NOT_FOUND)
+    /* No match.  */
+    {
+      if (DBG_LOOKUP)
+        log_debug ("%s: '%s' not found.\n", __func__, search_terms);
+
+      log_info (_("key \"%s\" not found\n"), search_terms);
+      if (!opt.quiet && source)
+        log_info (_("(check argument of option '%s')\n"), source);
+
+      goto out;
+    }
+  else if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
+    /* No more matches.  */
+    ;
+  else if (err)
+    /* Some other error.  An error message was already printed
+       out.  Free RESULTS and continue.  */
+    goto out;
+
+  /* Check for duplicates.  */
+  if (DBG_LOOKUP)
+    log_debug ("%s: Checking results of %s='%s' for dups\n",
+               __func__, source ? source : "user input", search_terms);
+  count = 0;
+  for (r = results; r; r = r->next)
+    {
+      pubkey_t *prevp;
+      pubkey_t next;
+      pubkey_t r2;
+      int dups = 0;
+
+      prevp = &r->next;
+      next = r->next;
+      while ((r2 = next))
+        {
+          if (cmp_public_keys (r->keyblock->pkt->pkt.public_key,
+                               r2->keyblock->pkt->pkt.public_key) != 0)
+            /* Not a dup.  */
+            {
+              prevp = &r2->next;
+              next = r2->next;
+              continue;
+            }
+
+          dups ++;
+          count ++;
+
+          /* Remove R2 from the list.  */
+          *prevp = r2->next;
+          release_kbnode (r2->keyblock);
+          next = r2->next;
+          xfree (r2);
+        }
+
+      if (dups)
+        {
+          hexfingerprint (r->keyblock->pkt->pkt.public_key,
+                          fingerprint, sizeof fingerprint);
+          if (! strlist_find (key_dups, fingerprint))
+            {
+              char fingerprint_formatted[MAX_FORMATTED_FINGERPRINT_LEN + 1];
+
+              log_info (_("Warning: %s appears in the keyring %d times\n"),
+                        format_hexfingerprint (fingerprint,
+                                               fingerprint_formatted,
+                                               sizeof fingerprint_formatted),
+                        1 + dups);
+              add_to_strlist (&key_dups, fingerprint);
+            }
+        }
+    }
+
+  if (DBG_LOOKUP && count)
+    {
+      log_debug ("After removing %d dups:\n", count);
+      for (r = results, count = 0; r; r = r->next)
+        log_debug ("  %d: %s\n",
+                   count,
+                   hexfingerprint (r->keyblock->pkt->pkt.public_key,
+                                   fingerprint, sizeof fingerprint));
+    }
+
+ out:
+  if (err)
+    pubkeys_free (results);
+  else
+    *r_keys = results;
+
+  return err;
+}
+
 
-  (void) ctx;
+static void
+pk_from_block (PKT_public_key *pk, kbnode_t keyblock, kbnode_t found_key)
+{
+  kbnode_t a = found_key ? found_key : keyblock;
 
-  assert (a->pkt->pkttype == PKT_PUBLIC_KEY
-         || a->pkt->pkttype == PKT_PUBLIC_SUBKEY);
+  log_assert (a->pkt->pkttype == PKT_PUBLIC_KEY
+              || a->pkt->pkttype == PKT_PUBLIC_SUBKEY);
 
   copy_public_key (pk, a->pkt->pkt.public_key);
 }
 
 
-/* For documentation see keydb.h.  */
+/* Return the public key with the key id KEYID and store it at PK.
+ * The resources in *PK should be released using
+ * release_public_key_parts().  This function also stores a copy of
+ * the public key in the user id cache (see cache_public_key).
+ *
+ * If PK is NULL, this function just stores the public key in the
+ * cache and returns the usual return code.
+ *
+ * PK->REQ_USAGE (which is a mask of PUBKEY_USAGE_SIG,
+ * PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT) is passed through to the
+ * lookup function.  If this is non-zero, only keys with the specified
+ * usage will be returned.  As such, it is essential that
+ * PK->REQ_USAGE be correctly initialized!
+ *
+ * Returns 0 on success, GPG_ERR_NO_PUBKEY if there is no public key
+ * with the specified key id, or another error code if an error
+ * occurs.
+ *
+ * If the data was not read from the cache, then the self-signed data
+ * has definitely been merged into the public key using
+ * merge_selfsigs.  */
 int
 get_pubkey (PKT_public_key * pk, u32 * keyid)
 {
@@ -437,7 +751,7 @@ get_pubkey (PKT_public_key * pk, u32 * keyid)
     rc = lookup (&ctx, &kb, &found_key, 0);
     if (!rc)
       {
-       pk_from_block (&ctx, pk, kb, found_key);
+       pk_from_block (pk, kb, found_key);
       }
     getkey_end (&ctx);
     release_kbnode (kb);
@@ -456,7 +770,16 @@ leave:
 }
 
 
-/* For documentation see keydb.h.  */
+/* Similar to get_pubkey, but it does not take PK->REQ_USAGE into
+ * account nor does it merge in the self-signed data.  This function
+ * also only considers primary keys.  It is intended to be used as a
+ * quick check of the key to avoid recursion.  It should only be used
+ * in very certain cases.  Like get_pubkey and unlike any of the other
+ * lookup functions, this function also consults the user id cache
+ * (see cache_public_key).
+ *
+ * Return the public key in *PK.  The resources in *PK should be
+ * released using release_public_key_parts().  */
 int
 get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
 {
@@ -465,7 +788,7 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
   KBNODE keyblock;
   u32 pkid[2];
 
-  assert (pk);
+  log_assert (pk);
 #if MAX_PK_CACHE_ENTRIES
   {
     /* Try to get it from the cache */
@@ -503,8 +826,8 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
       return GPG_ERR_NO_PUBKEY;
     }
 
-  assert (keyblock && keyblock->pkt
-          && keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
+  log_assert (keyblock && keyblock->pkt
+              && keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
 
   /* We return the primary key.  If KEYID matched a subkey, then we
      return an error.  */
@@ -523,8 +846,12 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
 }
 
 
-/* For documentation see keydb.h.  */
-KBNODE
+/* Return the key block for the key with key id KEYID or NULL, if an
+ * error occurs.  Use release_kbnode() to release the key block.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs.  */
+kbnode_t
 get_pubkeyblock (u32 * keyid)
 {
   struct getkey_ctx_s ctx;
@@ -548,7 +875,23 @@ get_pubkeyblock (u32 * keyid)
 }
 
 
-/* For documentation see keydb.h.  */
+/* Return the public key with the key id KEYID iff the secret key is
+ * available and store it at PK.  The resources should be released
+ * using release_public_key_parts().
+ *
+ * Unlike other lookup functions, PK may not be NULL.  PK->REQ_USAGE
+ * is passed through to the lookup function and is a mask of
+ * PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.  Thus, it
+ * must be valid!  If this is non-zero, only keys with the specified
+ * usage will be returned.
+ *
+ * Returns 0 on success.  If a public key with the specified key id is
+ * not found or a secret key is not available for that public key, an
+ * error code is returned.  Note: this function ignores legacy keys.
+ * An error code is also return if an error occurs.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs.  */
 gpg_error_t
 get_seckey (PKT_public_key *pk, u32 *keyid)
 {
@@ -571,7 +914,7 @@ get_seckey (PKT_public_key *pk, u32 *keyid)
   err = lookup (&ctx, &keyblock, &found_key, 1);
   if (!err)
     {
-      pk_from_block (&ctx, pk, keyblock, found_key);
+      pk_from_block (pk, keyblock, found_key);
     }
   getkey_end (&ctx);
   release_kbnode (keyblock);
@@ -636,7 +979,7 @@ skip_unusable (void *dummy, u32 * keyid, int uid_no)
 
       /* If UID_NO is non-zero, then the keyblock better have at least
         that many UIDs.  */
-      assert (uids_seen == uid_no);
+      log_assert (uids_seen == uid_no);
     }
 
   if (!unusable)
@@ -706,8 +1049,8 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
   if (retctx)
     {
       /* Reset the returned context in case of error.  */
-      assert (!ret_kdbhd); /* Not allowed because the handle is stored
-                             in the context.  */
+      log_assert (!ret_kdbhd); /* Not allowed because the handle is stored
+                                  in the context.  */
       *retctx = NULL;
     }
   if (ret_kdbhd)
@@ -777,7 +1120,7 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
   rc = lookup (ctx, ret_kb, &found_key, want_secret);
   if (!rc && pk)
     {
-      pk_from_block (ctx, pk, *ret_kb, found_key);
+      pk_from_block (pk, *ret_kb, found_key);
     }
 
   release_kbnode (help_kb);
@@ -798,7 +1141,56 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
 }
 
 
-/* For documentation see keydb.h.  */
+/* Find a public key identified by NAME.
+ *
+ * If name appears to be a valid RFC822 mailbox (i.e., email
+ * address) and auto key lookup is enabled (no_akl == 0), then the
+ * specified auto key lookup methods (--auto-key-lookup) are used to
+ * import the key into the local keyring.  Otherwise, just the local
+ * keyring is consulted.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results.  In this case, getkey_end() must be used to free the
+ * search context.  If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK.  Note: PK->REQ_USAGE must be valid!!!  PK->REQ_USAGE is
+ * passed through to the lookup function and is a mask of
+ * PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.  If this
+ * is non-zero, only keys with the specified usage will be returned.
+ * Note: The self-signed data has already been merged into the public
+ * key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * NAME is a string, which is turned into a search query using
+ * classify_user_id.
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK.  This should be freed using release_kbnode().
+ *
+ * If RET_KDBHD is not NULL, then the new database handle used to
+ * conduct the search is returned in *RET_KDBHD.  This can be used to
+ * get subsequent results using keydb_search_next or to modify the
+ * returned record.  Note: in this case, no advanced filtering is done
+ * for subsequent results (e.g., PK->REQ_USAGE is not respected).
+ * Unlike RETCTX, this is always returned.
+ *
+ * If INCLUDE_UNUSABLE is set, then unusable keys (see the
+ * documentation for skip_unusable for an exact definition) are
+ * skipped unless they are looked up by key id or by fingerprint.
+ *
+ * If NO_AKL is set, then the auto key locate functionality is
+ * disabled and only the local key ring is considered.  Note: the
+ * local key ring is consulted even if local is not in the
+ * --auto-key-locate option list!
+ *
+ * This function returns 0 on success.  Otherwise, an error code is
+ * returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found.  */
 int
 get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
                   const char *name, KBNODE * ret_keyblock,
@@ -811,6 +1203,9 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
   int nodefault = 0;
   int anylocalfirst = 0;
 
+  /* If RETCTX is not NULL, then RET_KDBHD must be NULL.  */
+  log_assert (retctx == NULL || ret_kdbhd == NULL);
+
   if (retctx)
     *retctx = NULL;
 
@@ -818,25 +1213,26 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
   is_mbox = is_valid_mailbox (name);
 
   /* The auto-key-locate feature works as follows: there are a number
-     of methods to look up keys.  By default, the local keyring is
-     tried first.  Then, each method listed in the --auto-key-locate is
-     tried in the order it appears.
-
-     This can be changed as follows:
-
-       - if nodefault appears anywhere in the list of options, then
-         the local keyring is not tried first, or,
-
-       - if local appears anywhere in the list of options, then the
-         local keyring is not tried first, but in the order in which
-         it was listed in the --auto-key-locate option.
-
-     Note: we only save the search context in RETCTX if the local
-     method is the first method tried (either explicitly or
-     implicitly).  */
+   * of methods to look up keys.  By default, the local keyring is
+   * tried first.  Then, each method listed in the --auto-key-locate is
+   * tried in the order it appears.
+   *
+   * This can be changed as follows:
+   *
+   *   - if nodefault appears anywhere in the list of options, then
+   *     the local keyring is not tried first, or,
+   *
+   *   - if local appears anywhere in the list of options, then the
+   *     local keyring is not tried first, but in the order in which
+   *     it was listed in the --auto-key-locate option.
+   *
+   * Note: we only save the search context in RETCTX if the local
+   * method is the first method tried (either explicitly or
+   * implicitly).  */
   if (!no_akl)
-    /* auto-key-locate is enabled.  */
     {
+      /* auto-key-locate is enabled.  */
+
       /* nodefault is true if "nodefault" or "local" appear.  */
       for (akl = opt.auto_key_locate; akl; akl = akl->next)
        if (akl->type == AKL_NODEFAULT || akl->type == AKL_LOCAL)
@@ -856,24 +1252,26 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
     }
 
   if (!nodefault)
-    /* "nodefault" didn't occur.  Thus, "local" is implicitly the
-       first method to try.  */
-    anylocalfirst = 1;
+    {
+      /* "nodefault" didn't occur.  Thus, "local" is implicitly the
+       *  first method to try.  */
+      anylocalfirst = 1;
+    }
 
   if (nodefault && is_mbox)
-    /* Either "nodefault" or "local" (explicitly) appeared in the auto
-       key locate list and NAME appears to be an email address.  Don't
-       try the local keyring.  */
     {
+      /* Either "nodefault" or "local" (explicitly) appeared in the
+       * auto key locate list and NAME appears to be an email address.
+       * Don't try the local keyring.  */
       rc = GPG_ERR_NO_PUBKEY;
     }
   else
-    /* Either "nodefault" and "local" don't appear in the auto key
-       locate list (in which case we try the local keyring first) or
-       NAME does not appear to be an email address (in which case we
-       only try the local keyring).  In this case, lookup NAME in the
-       local keyring.  */
     {
+      /* Either "nodefault" and "local" don't appear in the auto key
+       * locate list (in which case we try the local keyring first) or
+       * NAME does not appear to be an email address (in which case we
+       * only try the local keyring).  In this case, lookup NAME in
+       * the local keyring.  */
       add_to_strlist (&namelist, name);
       rc = key_byname (retctx, namelist, pk, 0,
                       include_unusable, ret_keyblock, ret_kdbhd);
@@ -882,16 +1280,16 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
   /* If the requested name resembles a valid mailbox and automatic
      retrieval has been enabled, we try to import the key. */
   if (gpg_err_code (rc) == GPG_ERR_NO_PUBKEY && !no_akl && is_mbox)
-    /* NAME wasn't present in the local keyring (or we didn't try the
-       local keyring).  Since the auto key locate feature is enabled
-       and NAME appears to be an email address, try the auto locate
-       feature.  */
     {
+      /* NAME wasn't present in the local keyring (or we didn't try
+       * the local keyring).  Since the auto key locate feature is
+       * enabled and NAME appears to be an email address, try the auto
+       * locate feature.  */
       for (akl = opt.auto_key_locate; akl; akl = akl->next)
        {
          unsigned char *fpr = NULL;
          size_t fpr_len;
-         int did_key_byname = 0;
+         int did_akl_local = 0;
          int no_fingerprint = 0;
          const char *mechanism = "?";
 
@@ -905,7 +1303,7 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
 
            case AKL_LOCAL:
              mechanism = "Local";
-             did_key_byname = 1;
+             did_akl_local = 1;
              if (retctx)
                {
                  getkey_end (*retctx);
@@ -938,6 +1336,13 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
              glo_ctrl.in_auto_key_retrieve--;
              break;
 
+           case AKL_WKD:
+             mechanism = "WKD";
+             glo_ctrl.in_auto_key_retrieve++;
+             rc = keyserver_import_wkd (ctrl, name, 0, &fpr, &fpr_len);
+             glo_ctrl.in_auto_key_retrieve--;
+             break;
+
            case AKL_LDAP:
              mechanism = "LDAP";
              glo_ctrl.in_auto_key_retrieve++;
@@ -947,12 +1352,12 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
 
            case AKL_KEYSERVER:
              /* Strictly speaking, we don't need to only use a valid
-                mailbox for the getname search, but it helps cut down
-                on the problem of searching for something like "john"
-                and getting a whole lot of keys back. */
-             if (opt.keyserver)
+              * mailbox for the getname search, but it helps cut down
+              * on the problem of searching for something like "john"
+              * and getting a whole lot of keys back. */
+             if (keyserver_any_configured (ctrl))
                {
-                 mechanism = opt.keyserver->uri;
+                 mechanism = "keyserver";
                  glo_ctrl.in_auto_key_retrieve++;
                  rc = keyserver_import_name (ctrl, name, &fpr, &fpr_len,
                                               opt.keyserver);
@@ -980,17 +1385,17 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
            }
 
          /* Use the fingerprint of the key that we actually fetched.
-            This helps prevent problems where the key that we fetched
-            doesn't have the same name that we used to fetch it.  In
-            the case of CERT and PKA, this is an actual security
-            requirement as the URL might point to a key put in by an
-            attacker.  By forcing the use of the fingerprint, we
-            won't use the attacker's key here. */
+          * This helps prevent problems where the key that we fetched
+          * doesn't have the same name that we used to fetch it.  In
+          * the case of CERT and PKA, this is an actual security
+          * requirement as the URL might point to a key put in by an
+          * attacker.  By forcing the use of the fingerprint, we
+          * won't use the attacker's key here. */
          if (!rc && fpr)
            {
              char fpr_string[MAX_FINGERPRINT_LEN * 2 + 1];
 
-             assert (fpr_len <= MAX_FINGERPRINT_LEN);
+             log_assert (fpr_len <= MAX_FINGERPRINT_LEN);
 
              free_strlist (namelist);
              namelist = NULL;
@@ -1003,22 +1408,20 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
 
              add_to_strlist (&namelist, fpr_string);
            }
-         else if (!rc && !fpr && !did_key_byname)
-           /* The acquisition method said no failure occurred, but it
-              didn't return a fingerprint.  That's a failure.  */
-           {
-             no_fingerprint = 1;
+         else if (!rc && !fpr && !did_akl_local)
+            { /* The acquisition method said no failure occurred, but
+               * it didn't return a fingerprint.  That's a failure.  */
+              no_fingerprint = 1;
              rc = GPG_ERR_NO_PUBKEY;
            }
          xfree (fpr);
          fpr = NULL;
 
-         if (!rc && !did_key_byname)
-           /* There was no error and we didn't do a local lookup.
-              This means that we imported a key into the local
-              keyring.  Try to read the imported key from the
-              keyring.  */
-           {
+         if (!rc && !did_akl_local)
+            { /* There was no error and we didn't do a local lookup.
+              * This means that we imported a key into the local
+              * keyring.  Try to read the imported key from the
+              * keyring.  */
              if (retctx)
                {
                  getkey_end (*retctx);
@@ -1052,7 +1455,7 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
 
   if (retctx && *retctx)
     {
-      assert (!(*retctx)->extra_list);
+      log_assert (!(*retctx)->extra_list);
       (*retctx)->extra_list = namelist;
     }
   else
@@ -1062,11 +1465,296 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
 }
 
 
-/* For documentation see keydb.h.
+\f
+
+/* Comparison machinery for get_best_pubkey_byname.  */
+
+/* First we have a struct to cache computed information about the key
+ * in question.  */
+struct pubkey_cmp_cookie
+{
+  int valid;                   /* Is this cookie valid?  */
+  PKT_public_key key;          /* The key.  */
+  PKT_user_id *uid;            /* The matching UID packet.  */
+  unsigned int validity;       /* Computed validity of (KEY, UID).  */
+  u32 creation_time;           /* Creation time of the newest subkey
+                                   capable of encryption.  */
+};
+
+
+/* Then we have a series of helper functions.  */
+static int
+key_is_ok (const PKT_public_key *key)
+{
+  return (! key->has_expired && ! key->flags.revoked
+          && key->flags.valid && ! key->flags.disabled);
+}
+
+
+static int
+uid_is_ok (const PKT_public_key *key, const PKT_user_id *uid)
+{
+  return key_is_ok (key) && ! uid->is_revoked;
+}
+
+
+static int
+subkey_is_ok (const PKT_public_key *sub)
+{
+  return ! sub->flags.revoked && sub->flags.valid && ! sub->flags.disabled;
+}
+
+
+/* Finally this function compares a NEW key to the former candidate
+ * OLD.  Returns < 0 if the old key is worse, > 0 if the old key is
+ * better, == 0 if it is a tie.  */
+static int
+pubkey_cmp (ctrl_t ctrl, const char *name, struct pubkey_cmp_cookie *old,
+            struct pubkey_cmp_cookie *new, KBNODE new_keyblock)
+{
+  kbnode_t n;
+
+  new->creation_time = 0;
+  for (n = find_next_kbnode (new_keyblock, PKT_PUBLIC_SUBKEY);
+       n; n = find_next_kbnode (n, PKT_PUBLIC_SUBKEY))
+    {
+      PKT_public_key *sub = n->pkt->pkt.public_key;
+
+      if ((sub->pubkey_usage & PUBKEY_USAGE_ENC) == 0)
+        continue;
+
+      if (! subkey_is_ok (sub))
+        continue;
+
+      if (sub->timestamp > new->creation_time)
+        new->creation_time = sub->timestamp;
+    }
+
+  for (n = find_next_kbnode (new_keyblock, PKT_USER_ID);
+       n; n = find_next_kbnode (n, PKT_USER_ID))
+    {
+      PKT_user_id *uid = n->pkt->pkt.user_id;
+      char *mbox = mailbox_from_userid (uid->name);
+      int match = mbox ? strcasecmp (name, mbox) == 0 : 0;
+
+      xfree (mbox);
+      if (! match)
+        continue;
+
+      new->uid = scopy_user_id (uid);
+      new->validity =
+        get_validity (ctrl, new_keyblock, &new->key, uid, NULL, 0) & TRUST_MASK;
+      new->valid = 1;
+
+      if (! old->valid)
+        return -1;     /* No OLD key.  */
+
+      if (! uid_is_ok (&old->key, old->uid) && uid_is_ok (&new->key, uid))
+        return -1;     /* Validity of the NEW key is better.  */
+
+      if (old->validity < new->validity)
+        return -1;     /* Validity of the NEW key is better.  */
+
+      if (old->validity == new->validity && uid_is_ok (&new->key, uid)
+          && old->creation_time < new->creation_time)
+        return -1;     /* Both keys are of the same validity, but the
+                           NEW key is newer.  */
+    }
+
+  /* Stick with the OLD key.  */
+  return 1;
+}
+
+
+/* This function works like get_pubkey_byname, but if the name
+ * resembles a mail address, the results are ranked and only the best
+ * result is returned.  */
+int
+get_best_pubkey_byname (ctrl_t ctrl, GETKEY_CTX *retctx, PKT_public_key *pk,
+                        const char *name, KBNODE *ret_keyblock,
+                        int include_unusable, int no_akl)
+{
+  int rc;
+  struct getkey_ctx_s *ctx = NULL;
+
+  if (retctx)
+    *retctx = NULL;
+
+  rc = get_pubkey_byname (ctrl, &ctx, pk, name, ret_keyblock,
+                          NULL, include_unusable, no_akl);
+  if (rc)
+    {
+      if (ctx)
+        getkey_end (ctx);
+      return rc;
+    }
+
+  if (is_valid_mailbox (name) && ctx)
+    {
+      /* Rank results and return only the most relevant key.  */
+      struct pubkey_cmp_cookie best = { 0 }, new;
+      KBNODE new_keyblock;
+      while (getkey_next (ctx, &new.key, &new_keyblock) == 0)
+        {
+          int diff = pubkey_cmp (ctrl, name, &best, &new, new_keyblock);
+          release_kbnode (new_keyblock);
+          if (diff < 0)
+            {
+              /* New key is better.  */
+              release_public_key_parts (&best.key);
+              free_user_id (best.uid);
+              best = new;
+            }
+          else if (diff > 0)
+            {
+              /* Old key is better.  */
+              release_public_key_parts (&new.key);
+              free_user_id (new.uid);
+            }
+          else
+            {
+              /* A tie.  Keep the old key.  */
+              release_public_key_parts (&new.key);
+              free_user_id (new.uid);
+            }
+        }
+      getkey_end (ctx);
+      ctx = NULL;
+      free_user_id (best.uid);
+
+      if (best.valid)
+        {
+          if (retctx || ret_keyblock)
+            {
+              ctx = xtrycalloc (1, sizeof **retctx);
+              if (! ctx)
+                rc = gpg_error_from_syserror ();
+              else
+                {
+                  ctx->kr_handle = keydb_new ();
+                  if (! ctx->kr_handle)
+                    {
+                      xfree (ctx);
+                      *retctx = NULL;
+                      rc = gpg_error_from_syserror ();
+                    }
+                  else
+                    {
+                      u32 *keyid = pk_keyid (&best.key);
+                      ctx->exact = 1;
+                      ctx->nitems = 1;
+                      ctx->items[0].mode = KEYDB_SEARCH_MODE_LONG_KID;
+                      ctx->items[0].u.kid[0] = keyid[0];
+                      ctx->items[0].u.kid[1] = keyid[1];
+
+                      if (ret_keyblock)
+                        {
+                          release_kbnode (*ret_keyblock);
+                          *ret_keyblock = NULL;
+                          rc = getkey_next (ctx, NULL, ret_keyblock);
+                        }
+                    }
+                }
+            }
+
+          if (pk)
+            *pk = best.key;
+          else
+            release_public_key_parts (&best.key);
+        }
+    }
+
+  if (rc && ctx)
+    {
+      getkey_end (ctx);
+      ctx = NULL;
+    }
+
+  if (retctx && ctx)
+    *retctx = ctx;
+  else
+    getkey_end (ctx);
+
+  return rc;
+}
+
+\f
+
+/* Get a public key from a file.
+ *
+ * PK is the buffer to store the key.  The caller needs to make sure
+ * that PK->REQ_USAGE is valid.  PK->REQ_USAGE is passed through to
+ * the lookup function and is a mask of PUBKEY_USAGE_SIG,
+ * PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.  If this is non-zero, only
+ * keys with the specified usage will be returned.
+ *
+ * FNAME is the file name.  That file should contain exactly one
+ * keyblock.
+ *
+ * This function returns 0 on success.  Otherwise, an error code is
+ * returned.  In particular, GPG_ERR_NO_PUBKEY is returned if the key
+ * is not found.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs.  The caller must release the content of PK by
+ * calling release_public_key_parts (or, if PK was malloced, using
+ * free_public_key).
+ */
+gpg_error_t
+get_pubkey_fromfile (ctrl_t ctrl, PKT_public_key *pk, const char *fname)
+{
+  gpg_error_t err;
+  kbnode_t keyblock;
+  kbnode_t found_key;
+  unsigned int infoflags;
+
+  err = read_key_from_file (ctrl, fname, &keyblock);
+  if (!err)
+    {
+      /* Warning: node flag bits 0 and 1 should be preserved by
+       * merge_selfsigs.  FIXME: Check whether this still holds. */
+      merge_selfsigs (keyblock);
+      found_key = finish_lookup (keyblock, pk->req_usage, 0, &infoflags);
+      print_status_key_considered (keyblock, infoflags);
+      if (found_key)
+        pk_from_block (pk, keyblock, found_key);
+      else
+        err = gpg_error (GPG_ERR_UNUSABLE_PUBKEY);
+    }
+
+  release_kbnode (keyblock);
+  return err;
+}
+
 
-   FIXME: We should replace this with the _byname function.  This can
-   be done by creating a userID conforming to the unified fingerprint
-   style.  */
+/* Lookup a key with the specified fingerprint.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK.  Note: this function does an exact search and thus the
+ * returned public key may be a subkey rather than the primary key.
+ * Note: The self-signed data has already been merged into the public
+ * key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If PK->REQ_USAGE is set, it is used to filter the search results.
+ * (Thus, if PK is not NULL, PK->REQ_USAGE must be valid!!!)  See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used.
+ *
+ * If R_KEYBLOCK is not NULL, then the first result's keyblock is
+ * returned in *R_KEYBLOCK.  This should be freed using
+ * release_kbnode().
+ *
+ * FPRINT is a byte array whose contents is the fingerprint to use as
+ * the search term.  FPRINT_LEN specifies the length of the
+ * fingerprint (in bytes).  Currently, only 16 and 20-byte
+ * fingerprints are supported.
+ *
+ * FIXME: We should replace this with the _byname function.  This can
+ * be done by creating a userID conforming to the unified fingerprint
+ * style.  */
 int
 get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
                     const byte * fprint, size_t fprint_len)
@@ -1095,7 +1783,7 @@ get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
       memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
       rc = lookup (&ctx, &kb, &found_key, 0);
       if (!rc && pk)
-       pk_from_block (&ctx, pk, kb, found_key);
+       pk_from_block (pk, kb, found_key);
       if (!rc && r_keyblock)
        {
          *r_keyblock = kb;
@@ -1110,7 +1798,16 @@ get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
 }
 
 
-/* For documentation see keydb.h.  */
+/* This function is similar to get_pubkey_byfprint, but it doesn't
+ * merge the self-signed data into the public key and subkeys or into
+ * the user ids.  It also doesn't add the key to the user id cache.
+ * Further, this function ignores PK->REQ_USAGE.
+ *
+ * This function is intended to avoid recursion and, as such, should
+ * only be used in very specific situations.
+ *
+ * Like get_pubkey_byfprint, PK may be NULL.  In that case, this
+ * function effectively just checks for the existence of the key.  */
 int
 get_pubkey_byfprint_fast (PKT_public_key * pk,
                          const byte * fprint, size_t fprint_len)
@@ -1144,8 +1841,8 @@ get_pubkey_byfprint_fast (PKT_public_key * pk,
       return GPG_ERR_NO_PUBKEY;
     }
 
-  assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY
-         || keyblock->pkt->pkttype == PKT_PUBLIC_SUBKEY);
+  log_assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY
+              || keyblock->pkt->pkttype == PKT_PUBLIC_SUBKEY);
   if (pk)
     copy_public_key (pk, keyblock->pkt->pkt.public_key);
   release_kbnode (keyblock);
@@ -1168,6 +1865,7 @@ parse_def_secret_key (ctrl_t ctrl)
       gpg_error_t err;
       KEYDB_SEARCH_DESC desc;
       KBNODE kb;
+      KBNODE node;
 
       err = classify_user_id (t->d, &desc, 1);
       if (err)
@@ -1208,16 +1906,71 @@ parse_def_secret_key (ctrl_t ctrl)
           continue;
         }
 
-      err = agent_probe_secret_key (ctrl, kb->pkt->pkt.public_key);
+      merge_selfsigs (kb);
+
+      err = gpg_error (GPG_ERR_NO_SECKEY);
+      node = kb;
+      do
+        {
+          PKT_public_key *pk = node->pkt->pkt.public_key;
+
+          /* Check that the key has the signing capability.  */
+          if (! (pk->pubkey_usage & PUBKEY_USAGE_SIG))
+            continue;
+
+          /* Check if the key is valid.  */
+          if (pk->flags.revoked)
+            {
+              if (DBG_LOOKUP)
+                log_debug ("not using %s as default key, %s",
+                           keystr_from_pk (pk), "revoked");
+              continue;
+            }
+          if (pk->has_expired)
+            {
+              if (DBG_LOOKUP)
+                log_debug ("not using %s as default key, %s",
+                           keystr_from_pk (pk), "expired");
+              continue;
+            }
+          if (pk_is_disabled (pk))
+            {
+              if (DBG_LOOKUP)
+                log_debug ("not using %s as default key, %s",
+                           keystr_from_pk (pk), "disabled");
+              continue;
+            }
+
+          err = agent_probe_secret_key (ctrl, pk);
+          if (! err)
+            /* This is a valid key.  */
+            break;
+        }
+      while ((node = find_next_kbnode (node, PKT_PUBLIC_SUBKEY)));
+
       release_kbnode (kb);
-      if (err)
+      if (err)
         {
-          if (! warned)
-            log_info (_("using \"%s\" as default secret key\n"), t->d);
+          if (! warned && ! opt.quiet)
+            {
+              log_info (_("Warning: not using '%s' as default key: %s\n"),
+                        t->d, gpg_strerror (GPG_ERR_NO_SECKEY));
+              print_reported_error (err, GPG_ERR_NO_SECKEY);
+            }
+        }
+      else
+        {
+          if (! warned && ! opt.quiet)
+            log_info (_("using \"%s\" as default secret key for signing\n"),
+                      t->d);
           break;
         }
     }
 
+  if (! warned && opt.def_secret_key && ! t)
+    log_info (_("all values passed to '%s' ignored\n"),
+              "--default-key");
+
   warned = 1;
 
   if (hd)
@@ -1228,7 +1981,30 @@ parse_def_secret_key (ctrl_t ctrl)
   return NULL;
 }
 
-/* For documentation see keydb.h.  */
+
+/* Look up a secret key.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
+ * set, it is used to filter the search results.  See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used.  Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If --default-key was set, then the specified key is looked up.  (In
+ * this case, the default key is returned even if it is considered
+ * unusable.  See the documentation for skip_unusable for exactly what
+ * this means.)
+ *
+ * Otherwise, this initiates a DB scan that returns all keys that are
+ * usable (see previous paragraph for exactly what usable means) and
+ * for which a secret key is available.
+ *
+ * This function returns the first match.  Additional results can be
+ * returned using getkey_next.  */
 gpg_error_t
 get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
 {
@@ -1249,8 +2025,44 @@ get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
 
   return err;
 }
+
+
 \f
-/* For documentation see keydb.h.  */
+/* Search for keys matching some criteria.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results.  In this case, getkey_end() must be used to free the
+ * search context.  If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
+ * set, it is used to filter the search results.  See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used.  Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If NAMES is not NULL, then a search query is constructed using
+ * classify_user_id on each of the strings in the list.  (Recall: the
+ * database does an OR of the terms, not an AND.)  If NAMES is
+ * NULL, then all results are returned.
+ *
+ * If WANT_SECRET is set, then only keys with an available secret key
+ * (either locally or via key registered on a smartcard) are returned.
+ *
+ * This function does not skip unusable keys (see the documentation
+ * for skip_unusable for an exact definition).
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK.  This should be freed using release_kbnode().
+ *
+ * This function returns 0 on success.  Otherwise, an error code is
+ * returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found.  */
 gpg_error_t
 getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
                 strlist_t names, int want_secret, kbnode_t *ret_keyblock)
@@ -1260,7 +2072,46 @@ getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
 }
 
 
-/* For documentation see keydb.h.  */
+/* Search for one key matching some criteria.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results.  In this case, getkey_end() must be used to free the
+ * search context.  If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
+ * set, it is used to filter the search results.  See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used.  Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If NAME is not NULL, then a search query is constructed using
+ * classify_user_id on the string.  In this case, even unusable keys
+ * (see the documentation for skip_unusable for an exact definition of
+ * unusable) are returned.  Otherwise, if --default-key was set, then
+ * that key is returned (even if it is unusable).  If neither of these
+ * conditions holds, then the first usable key is returned.
+ *
+ * If WANT_SECRET is set, then only keys with an available secret key
+ * (either locally or via key registered on a smartcard) are returned.
+ *
+ * This function does not skip unusable keys (see the documentation
+ * for skip_unusable for an exact definition).
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK.  This should be freed using release_kbnode().
+ *
+ * This function returns 0 on success.  Otherwise, an error code is
+ * returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found.
+ *
+ * FIXME: We also have the get_pubkey_byname function which has a
+ * different semantic.  Should be merged with this one.  */
 gpg_error_t
 getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
                const char *name, int want_secret, kbnode_t *ret_keyblock)
@@ -1292,11 +2143,27 @@ getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
 }
 
 
-/* For documentation see keydb.h.  */
+/* Return the next search result.
+ *
+ * If PK is not NULL, the public key of the next result is returned in
+ * *PK.  Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs.  Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xmalloc, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * RET_KEYBLOCK can be given as NULL; if it is not NULL it the entire
+ * found keyblock is returned which must be released with
+ * release_kbnode.  If the function returns an error NULL is stored at
+ * RET_KEYBLOCK.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs.  */
 gpg_error_t
 getkey_next (getkey_ctx_t ctx, PKT_public_key *pk, kbnode_t *ret_keyblock)
 {
   int rc; /* Fixme:  Make sure this is proper gpg_error */
+  KBNODE keyblock = NULL;
   KBNODE found_key = NULL;
 
   /* We need to disable the caching so that for an exact key search we
@@ -1305,15 +2172,26 @@ getkey_next (getkey_ctx_t ctx, PKT_public_key *pk, kbnode_t *ret_keyblock)
      used without respecting the current file pointer!  */
   keydb_disable_caching (ctx->kr_handle);
 
-  rc = lookup (ctx, ret_keyblock, &found_key, ctx->want_secret);
-  if (!rc && pk && ret_keyblock)
-    pk_from_block (ctx, pk, *ret_keyblock, found_key);
+  /* FOUND_KEY is only valid as long as RET_KEYBLOCK is.  If the
+   * caller wants PK, but not RET_KEYBLOCK, we need hand in our own
+   * keyblock.  */
+  if (pk && ret_keyblock == NULL)
+      ret_keyblock = &keyblock;
+
+  rc = lookup (ctx, ret_keyblock, pk ? &found_key : NULL, ctx->want_secret);
+  if (!rc && pk)
+    {
+      log_assert (found_key);
+      pk_from_block (pk, NULL, found_key);
+      release_kbnode (keyblock);
+    }
 
   return rc;
 }
 
 
-/* For documentation see keydb.h.  */
+/* Release any resources used by a key listing context.  This must be
+ * called on the context returned by, e.g., getkey_byname.  */
 void
 getkey_end (getkey_ctx_t ctx)
 {
@@ -1332,7 +2210,10 @@ getkey_end (getkey_ctx_t ctx)
  ************* Merging stuff ********************
  ************************************************/
 
-/* For documentation see keydb.h.  */
+/* Set the mainkey_id fields for all keys in KEYBLOCK.  This is
+ * usually done by merge_selfsigs but at some places we only need the
+ * main_kid not a full merge.  The function also guarantees that all
+ * pk->keyids are computed.  */
 void
 setup_main_keyids (kbnode_t keyblock)
 {
@@ -1361,7 +2242,13 @@ setup_main_keyids (kbnode_t keyblock)
 }
 
 
-/* For documentation see keydb.h.  */
+/* KEYBLOCK corresponds to a public key block.  This function merges
+ * much of the information from the self-signed data into the public
+ * key, public subkey and user id data structures.  If you use the
+ * high-level search API (e.g., get_pubkey) for looking up key blocks,
+ * then you don't need to call this function.  This function is
+ * useful, however, if you change the keyblock, e.g., by adding or
+ * removing a self-signed data packet.  */
 void
 merge_keys_and_selfsig (KBNODE keyblock)
 {
@@ -1859,7 +2746,7 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
              else if ((IS_UID_SIG (sig) || IS_UID_REV (sig))
                       && sig->timestamp >= sigdate)
                {
-                 /* Note: we allow to invalidate cert revocations
+                 /* Note: we allow invalidation of cert revocations
                   * by a newer signature.  An attacker can't use this
                   * because a key should be revoked with a key revocation.
                   * The reason why we have to allow for that is that at
@@ -2182,6 +3069,7 @@ merge_selfsigs_subkey (KBNODE keyblock, KBNODE subnode)
   keytimestamp = subpk->timestamp;
 
   subpk->flags.valid = 0;
+  subpk->flags.exact = 0;
   subpk->main_keyid[0] = mainpk->main_keyid[0];
   subpk->main_keyid[1] = mainpk->main_keyid[1];
 
@@ -2446,82 +3334,97 @@ merge_selfsigs (KBNODE keyblock)
 
 \f
 /* See whether the key satisfies any additional requirements specified
-   in CTX.  If so, return 1 and set CTX->FOUND_KEY to an appropriate
-   key or subkey.  Otherwise, return 0 if there was no appropriate
-   key.
-
-   In case the primary key is not required, select a suitable subkey.
-   We need the primary key if PUBKEY_USAGE_CERT is set in
-   CTX->REQ_USAGE or we are in PGP6 or PGP7 mode and PUBKEY_USAGE_SIG
-   is set in CTX->REQ_USAGE.
-
-   If any of PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT
-   are set in CTX->REQ_USAGE, we filter by the key's function.
-   Concretely, if PUBKEY_USAGE_SIG and PUBKEY_USAGE_CERT are set, then
-   we only return a key if it is (at least) either a signing or a
-   certification key.
-
-   If CTX->REQ_USAGE is set, then we reject any keys that are not good
-   (i.e., valid, not revoked, not expired, etc.).  This allows the
-   getkey functions to be used for plain key listings.
-
-   Sets the matched key's user id field (pk->user_id) to the user id
-   that matched the low-level search criteria or NULL.
-
-
-   This function needs to handle several different cases:
-
-    1. No requested usage and no primary key requested
-       Examples for this case are that we have a keyID to be used
-       for decrytion or verification.
-    2. No usage but primary key requested
-       This is the case for all functions which work on an
-       entire keyblock, e.g. for editing or listing
-    3. Usage and primary key requested
-       FXME
-    4. Usage but no primary key requested
-       FIXME
-
+ * in CTX.  If so, return the node of an appropriate key or subkey.
+ * Otherwise, return NULL if there was no appropriate key.
+ *
+ * Note that we do not return a reference, i.e. the result must not be
+ * freed using 'release_kbnode'.
+ *
+ * In case the primary key is not required, select a suitable subkey.
+ * We need the primary key if PUBKEY_USAGE_CERT is set in REQ_USAGE or
+ * we are in PGP6 or PGP7 mode and PUBKEY_USAGE_SIG is set in
+ * REQ_USAGE.
+ *
+ * If any of PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT
+ * are set in REQ_USAGE, we filter by the key's function.  Concretely,
+ * if PUBKEY_USAGE_SIG and PUBKEY_USAGE_CERT are set, then we only
+ * return a key if it is (at least) either a signing or a
+ * certification key.
+ *
+ * If REQ_USAGE is set, then we reject any keys that are not good
+ * (i.e., valid, not revoked, not expired, etc.).  This allows the
+ * getkey functions to be used for plain key listings.
+ *
+ * Sets the matched key's user id field (pk->user_id) to the user id
+ * that matched the low-level search criteria or NULL.
+ *
+ * If R_FLAGS is not NULL set certain flags for more detailed error
+ * reporting.  Used flags are:
+ *
+ * - LOOKUP_ALL_SUBKEYS_EXPIRED :: All Subkeys are expired or have
+ *                                 been revoked.
+ * - LOOKUP_NOT_SELECTED :: No suitable key found
+ *
+ * This function needs to handle several different cases:
+ *
+ *  1. No requested usage and no primary key requested
+ *     Examples for this case are that we have a keyID to be used
+ *     for decrytion or verification.
+ *  2. No usage but primary key requested
+ *     This is the case for all functions which work on an
+ *     entire keyblock, e.g. for editing or listing
+ *  3. Usage and primary key requested
+ *     FIXME
+ *  4. Usage but no primary key requested
+ *     FIXME
+ *
  */
-static KBNODE
-finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
+static kbnode_t
+finish_lookup (kbnode_t keyblock, unsigned int req_usage, int want_exact,
+               unsigned int *r_flags)
 {
-  KBNODE k;
+  kbnode_t k;
 
-  /* If CTX->EXACT is set, the key or subkey that actually matched the
+  /* If WANT_EXACT is set, the key or subkey that actually matched the
      low-level search criteria.  */
-  KBNODE foundk = NULL;
+  kbnode_t foundk = NULL;
   /* The user id (if any) that matched the low-level search criteria.  */
   PKT_user_id *foundu = NULL;
 
-#define USAGE_MASK  (PUBKEY_USAGE_SIG|PUBKEY_USAGE_ENC|PUBKEY_USAGE_CERT)
-  unsigned int req_usage = (ctx->req_usage & USAGE_MASK);
+  u32 latest_date;
+  kbnode_t latest_key;
+  PKT_public_key *pk;
+  int req_prim;
+  u32 curtime = make_timestamp ();
 
-  /* Request the primary if we're certifying another key, and also
-     if signing data while --pgp6 or --pgp7 is on since pgp 6 and 7
-     do not understand signatures made by a signing subkey.  PGP 8
-     does. */
-  int req_prim = (ctx->req_usage & PUBKEY_USAGE_CERT) ||
-    ((PGP6 || PGP7) && (ctx->req_usage & PUBKEY_USAGE_SIG));
+  if (r_flags)
+    *r_flags = 0;
 
-  u32 curtime = make_timestamp ();
+#define USAGE_MASK  (PUBKEY_USAGE_SIG|PUBKEY_USAGE_ENC|PUBKEY_USAGE_CERT)
+  req_usage &= USAGE_MASK;
+
+  /* Request the primary if we're certifying another key, and also if
+   * signing data while --pgp6 or --pgp7 is on since pgp 6 and 7 do
+   * not understand signatures made by a signing subkey.  PGP 8 does. */
+  req_prim = ((req_usage & PUBKEY_USAGE_CERT)
+              || ((PGP6 || PGP7) && (req_usage & PUBKEY_USAGE_SIG)));
 
-  u32 latest_date;
-  KBNODE latest_key;
 
-  assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
+  log_assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
 
-  if (ctx->exact)
-    /* Get the key or subkey that matched the low-level search
-       criteria.  */
+  /* For an exact match mark the primary or subkey that matched the
+     low-level search criteria.  */
+  if (want_exact)
     {
       for (k = keyblock; k; k = k->next)
        {
          if ((k->flag & 1))
            {
-             assert (k->pkt->pkttype == PKT_PUBLIC_KEY
-                     || k->pkt->pkttype == PKT_PUBLIC_SUBKEY);
+             log_assert (k->pkt->pkttype == PKT_PUBLIC_KEY
+                          || k->pkt->pkttype == PKT_PUBLIC_SUBKEY);
              foundk = k;
+              pk = k->pkt->pkt.public_key;
+              pk->flags.exact = 1;
              break;
            }
        }
@@ -2532,7 +3435,7 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
     {
       if ((k->flag & 2))
        {
-         assert (k->pkt->pkttype == PKT_USER_ID);
+         log_assert (k->pkt->pkttype == PKT_USER_ID);
          foundu = k->pkt->pkt.user_id;
          break;
        }
@@ -2551,26 +3454,28 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
 
   latest_date = 0;
   latest_key = NULL;
-  /* Set latest_key to the latest (the one with the most recent
-     timestamp) good (valid, not revoked, not expired, etc.) subkey.
-
-     Don't bother if we are only looking for a primary key or we need
-     an exact match and the exact match is not a subkey.  */
+  /* Set LATEST_KEY to the latest (the one with the most recent
+   * timestamp) good (valid, not revoked, not expired, etc.) subkey.
+   *
+   * Don't bother if we are only looking for a primary key or we need
+   * an exact match and the exact match is not a subkey.  */
   if (req_prim || (foundk && foundk->pkt->pkttype != PKT_PUBLIC_SUBKEY))
     ;
   else
     {
-      KBNODE nextk;
+      kbnode_t nextk;
+      int n_subkeys = 0;
+      int n_revoked_or_expired = 0;
 
       /* Either start a loop or check just this one subkey.  */
       for (k = foundk ? foundk : keyblock; k; k = nextk)
        {
-         PKT_public_key *pk;
-
          if (foundk)
-           /* If FOUNDK is not NULL, then only consider that exact
-              key, i.e., don't iterate.  */
-           nextk = NULL;
+            {
+              /* If FOUNDK is not NULL, then only consider that exact
+                 key, i.e., don't iterate.  */
+              nextk = NULL;
+            }
          else
            nextk = k->next;
 
@@ -2581,22 +3486,34 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
          if (DBG_LOOKUP)
            log_debug ("\tchecking subkey %08lX\n",
                       (ulong) keyid_from_pk (pk, NULL));
+
          if (!pk->flags.valid)
            {
              if (DBG_LOOKUP)
                log_debug ("\tsubkey not valid\n");
              continue;
            }
+         if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
+           {
+             if (DBG_LOOKUP)
+               log_debug ("\tusage does not match: want=%x have=%x\n",
+                          req_usage, pk->pubkey_usage);
+             continue;
+           }
+
+          n_subkeys++;
          if (pk->flags.revoked)
            {
              if (DBG_LOOKUP)
                log_debug ("\tsubkey has been revoked\n");
+              n_revoked_or_expired++;
              continue;
            }
          if (pk->has_expired)
            {
              if (DBG_LOOKUP)
                log_debug ("\tsubkey has expired\n");
+              n_revoked_or_expired++;
              continue;
            }
          if (pk->timestamp > curtime && !opt.ignore_valid_from)
@@ -2606,14 +3523,6 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
              continue;
            }
 
-         if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
-           {
-             if (DBG_LOOKUP)
-               log_debug ("\tusage does not match: want=%x have=%x\n",
-                          req_usage, pk->pubkey_usage);
-             continue;
-           }
-
          if (DBG_LOOKUP)
            log_debug ("\tsubkey might be fine\n");
          /* In case a key has a timestamp of 0 set, we make sure
@@ -2626,21 +3535,22 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
              latest_key = k;
            }
        }
+      if (n_subkeys == n_revoked_or_expired && r_flags)
+        *r_flags |= LOOKUP_ALL_SUBKEYS_EXPIRED;
     }
 
   /* Check if the primary key is ok (valid, not revoke, not expire,
-     matches requested usage) if:
-
-       - we didn't find an appropriate subkey and we're not doing an
-         exact search,
-
-       - we're doing an exact match and the exact match was the
-         primary key, or,
-
-       - we're just considering the primary key.  */
-  if ((!latest_key && !ctx->exact) || foundk == keyblock || req_prim)
+   * matches requested usage) if:
+   *
+   *   - we didn't find an appropriate subkey and we're not doing an
+   *     exact search,
+   *
+   *   - we're doing an exact match and the exact match was the
+   *     primary key, or,
+   *
+   *   - we're just considering the primary key.  */
+  if ((!latest_key && !want_exact) || foundk == keyblock || req_prim)
     {
-      PKT_public_key *pk;
       if (DBG_LOOKUP && !foundk && !req_prim)
        log_debug ("\tno suitable subkeys found - trying primary\n");
       pk = keyblock->pkt->pkt.public_key;
@@ -2649,6 +3559,12 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
          if (DBG_LOOKUP)
            log_debug ("\tprimary key not valid\n");
        }
+      else if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
+       {
+         if (DBG_LOOKUP)
+           log_debug ("\tprimary key usage does not match: "
+                      "want=%x have=%x\n", req_usage, pk->pubkey_usage);
+       }
       else if (pk->flags.revoked)
        {
          if (DBG_LOOKUP)
@@ -2659,18 +3575,11 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
          if (DBG_LOOKUP)
            log_debug ("\tprimary key has expired\n");
        }
-      else if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
-       {
-         if (DBG_LOOKUP)
-           log_debug ("\tprimary key usage does not match: "
-                      "want=%x have=%x\n", req_usage, pk->pubkey_usage);
-       }
       else /* Okay.  */
        {
          if (DBG_LOOKUP)
            log_debug ("\tprimary key may be used\n");
          latest_key = keyblock;
-         latest_date = pk->timestamp;
        }
     }
 
@@ -2678,19 +3587,20 @@ finish_lookup (GETKEY_CTX ctx, KBNODE keyblock)
     {
       if (DBG_LOOKUP)
        log_debug ("\tno suitable key found -  giving up\n");
+      if (r_flags)
+        *r_flags |= LOOKUP_NOT_SELECTED;
       return NULL; /* Not found.  */
     }
 
-found:
+ found:
   if (DBG_LOOKUP)
     log_debug ("\tusing key %08lX\n",
               (ulong) keyid_from_pk (latest_key->pkt->pkt.public_key, NULL));
 
   if (latest_key)
     {
-      PKT_public_key *pk = latest_key->pkt->pkt.public_key;
-      if (pk->user_id)
-       free_user_id (pk->user_id);
+      pk = latest_key->pkt->pkt.public_key;
+      free_user_id (pk->user_id);
       pk->user_id = scopy_user_id (foundu);
     }
 
@@ -2709,6 +3619,34 @@ found:
 }
 
 
+/* Print a KEY_CONSIDERED status line.  */
+static void
+print_status_key_considered (kbnode_t keyblock, unsigned int flags)
+{
+  char hexfpr[2*MAX_FINGERPRINT_LEN + 1];
+  kbnode_t node;
+  char flagbuf[20];
+
+  if (!is_status_enabled ())
+    return;
+
+  for (node=keyblock; node; node = node->next)
+    if (node->pkt->pkttype == PKT_PUBLIC_KEY
+        || node->pkt->pkttype == PKT_SECRET_KEY)
+      break;
+  if (!node)
+    {
+      log_error ("%s: keyblock w/o primary key\n", __func__);
+      return;
+    }
+
+  hexfingerprint (node->pkt->pkt.public_key, hexfpr, sizeof hexfpr);
+  snprintf (flagbuf, sizeof flagbuf, " %u", flags);
+  write_status_strings (STATUS_KEY_CONSIDERED, hexfpr, flagbuf, NULL);
+}
+
+
+
 /* A high-level function to lookup keys.
 
    This function builds on top of the low-level keydb API.  It first
@@ -2720,7 +3658,12 @@ found:
    all of the self-signed data into the keys, subkeys and user id
    packets (see the merge_selfsigs for details).
 
-   On success the key's keyblock is stored at *RET_KEYBLOCK.  */
+   On success the key's keyblock is stored at *RET_KEYBLOCK, and the
+   specific subkey is stored at *RET_FOUND_KEY.  Note that we do not
+   return a reference in *RET_FOUND_KEY, i.e. the result must not be
+   freed using 'release_kbnode', and it is only valid until
+   *RET_KEYBLOCK is deallocated.  Therefore, if RET_FOUND_KEY is not
+   NULL, then RET_KEYBLOCK must not be NULL.  */
 static int
 lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
        int want_secret)
@@ -2729,6 +3672,11 @@ lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
   int no_suitable_key = 0;
   KBNODE keyblock = NULL;
   KBNODE found_key = NULL;
+  unsigned int infoflags;
+
+  log_assert (ret_found_key == NULL || ret_keyblock != NULL);
+  if (ret_keyblock)
+    *ret_keyblock = NULL;
 
   for (;;)
     {
@@ -2747,7 +3695,6 @@ lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
       if (rc)
        {
          log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (rc));
-         rc = 0;
          goto skip;
        }
 
@@ -2755,17 +3702,20 @@ lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
         goto skip; /* No secret key available.  */
 
       /* Warning: node flag bits 0 and 1 should be preserved by
-       * merge_selfsigs.  For secret keys, premerge transferred the
-       * keys to the keyblock.  */
+       * merge_selfsigs.  */
       merge_selfsigs (keyblock);
-      found_key = finish_lookup (ctx, keyblock);
+      found_key = finish_lookup (keyblock, ctx->req_usage, ctx->exact,
+                                 &infoflags);
+      print_status_key_considered (keyblock, infoflags);
       if (found_key)
        {
          no_suitable_key = 0;
          goto found;
        }
       else
-       no_suitable_key = 1;
+        {
+          no_suitable_key = 1;
+        }
 
     skip:
       /* Release resources and continue search. */
@@ -2779,14 +3729,17 @@ lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
       keydb_disable_caching (ctx->kr_handle);
     }
 
-found:
+ found:
   if (rc && gpg_err_code (rc) != GPG_ERR_NOT_FOUND)
     log_error ("keydb_search failed: %s\n", gpg_strerror (rc));
 
   if (!rc)
     {
-      *ret_keyblock = keyblock; /* Return the keyblock.  */
-      keyblock = NULL;
+      if (ret_keyblock)
+        {
+          *ret_keyblock = keyblock; /* Return the keyblock.  */
+          keyblock = NULL;
+        }
     }
   else if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND && no_suitable_key)
     rc = want_secret? GPG_ERR_UNUSABLE_SECKEY : GPG_ERR_UNUSABLE_PUBKEY;
@@ -2807,12 +3760,44 @@ found:
 }
 
 
-/* For documentation see keydb.h.  */
+/* Enumerate some secret keys (specifically, those specified with
+ * --default-key and --try-secret-key).  Use the following procedure:
+ *
+ *  1) Initialize a void pointer to NULL
+ *  2) Pass a reference to this pointer to this function (content)
+ *     and provide space for the secret key (sk)
+ *  3) Call this function as long as it does not return an error (or
+ *     until you are done).  The error code GPG_ERR_EOF indicates the
+ *     end of the listing.
+ *  4) Call this function a last time with SK set to NULL,
+ *     so that can free it's context.
+ *
+ * In pseudo-code:
+ *
+ *   void *ctx = NULL;
+ *   PKT_public_key *sk = xmalloc_clear (sizeof (*sk));
+ *
+ *   while ((err = enum_secret_keys (&ctx, sk)))
+ *     { // Process SK.
+ *       if (done)
+ *         break;
+ *       free_public_key (sk);
+ *       sk = xmalloc_clear (sizeof (*sk));
+ *     }
+ *
+ *   // Release any resources used by CTX.
+ *   enum_secret_keys (&ctx, NULL);
+ *   free_public_key (sk);
+ *
+ *   if (gpg_err_code (err) != GPG_ERR_EOF)
+ *     ; // An error occurred.
+ */
 gpg_error_t
 enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
 {
   gpg_error_t err = 0;
   const char *name;
+  kbnode_t keyblock;
   struct
   {
     int eof;
@@ -2820,6 +3805,7 @@ enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
     strlist_t sl;
     kbnode_t keyblock;
     kbnode_t node;
+    getkey_ctx_t ctx;
   } *c = *context;
 
   if (!c)
@@ -2835,6 +3821,7 @@ enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
     {
       /* Free the context.  */
       release_kbnode (c->keyblock);
+      getkey_end (c->ctx);
       xfree (c);
       *context = NULL;
       return 0;
@@ -2852,6 +3839,7 @@ enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
           do
             {
               name = NULL;
+              keyblock = NULL;
               switch (c->state)
                 {
                 case 0: /* First try to use the --default-key.  */
@@ -2874,24 +3862,57 @@ enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
                     c->state++;
                   break;
 
+                case 3: /* Init search context to enum all secret keys.  */
+                  err = getkey_bynames (&c->ctx, NULL, NULL, 1, &keyblock);
+                  if (err)
+                    {
+                      release_kbnode (keyblock);
+                      keyblock = NULL;
+                      getkey_end (c->ctx);
+                      c->ctx = NULL;
+                    }
+                  c->state++;
+                  break;
+
+                case 4: /* Get next item from the context.  */
+                  if (c->ctx)
+                    {
+                      err = getkey_next (c->ctx, NULL, &keyblock);
+                      if (err)
+                        {
+                          release_kbnode (keyblock);
+                          keyblock = NULL;
+                          getkey_end (c->ctx);
+                          c->ctx = NULL;
+                        }
+                    }
+                  else
+                    c->state++;
+                  break;
+
                 default: /* No more names to check - stop.  */
                   c->eof = 1;
                   return gpg_error (GPG_ERR_EOF);
                 }
             }
-          while (!name || !*name);
+          while ((!name || !*name) && !keyblock);
 
-          err = getkey_byname (ctrl, NULL, NULL, name, 1, &c->keyblock);
-          if (err)
+          if (keyblock)
+            c->node = c->keyblock = keyblock;
+          else
             {
-              /* getkey_byname might return a keyblock even in the
-                 error case - I have not checked.  Thus better release
-                 it.  */
-              release_kbnode (c->keyblock);
-              c->keyblock = NULL;
+              err = getkey_byname (ctrl, NULL, NULL, name, 1, &c->keyblock);
+              if (err)
+                {
+                  /* getkey_byname might return a keyblock even in the
+                     error case - I have not checked.  Thus better release
+                     it.  */
+                  release_kbnode (c->keyblock);
+                  c->keyblock = NULL;
+                }
+              else
+                c->node = c->keyblock;
             }
-          else
-            c->node = c->keyblock;
         }
 
       /* Get the next key from the current keyblock.  */
@@ -3070,8 +4091,8 @@ get_user_id_byfpr_native (const byte *fpr)
 }
 
 
-
-/* For documentation see keydb.h.  */
+/* Return the database handle used by this context.  The context still
+   owns the handle.  */
 KEYDB_HANDLE
 get_ctx_handle (GETKEY_CTX ctx)
 {
@@ -3132,14 +4153,14 @@ parse_auto_key_locate (char *options)
        akl->type = AKL_LDAP;
       else if (ascii_strcasecmp (tok, "keyserver") == 0)
        akl->type = AKL_KEYSERVER;
-#ifdef USE_DNS_CERT
       else if (ascii_strcasecmp (tok, "cert") == 0)
        akl->type = AKL_CERT;
-#endif
       else if (ascii_strcasecmp (tok, "pka") == 0)
        akl->type = AKL_PKA;
       else if (ascii_strcasecmp (tok, "dane") == 0)
        akl->type = AKL_DANE;
+      else if (ascii_strcasecmp (tok, "wkd") == 0)
+       akl->type = AKL_WKD;
       else if ((akl->spec = parse_keyserver_uri (tok, 1)))
        akl->type = AKL_SPEC;
       else
@@ -3219,8 +4240,8 @@ have_secret_key_with_kid (u32 *keyid)
              match a single key or subkey.  */
          if ((node->flag & 1))
             {
-              assert (node->pkt->pkttype == PKT_PUBLIC_KEY
-                      || node->pkt->pkttype == PKT_PUBLIC_SUBKEY);
+              log_assert (node->pkt->pkttype == PKT_PUBLIC_KEY
+                          || node->pkt->pkttype == PKT_PUBLIC_SUBKEY);
 
               if (!agent_probe_secret_key (NULL, node->pkt->pkt.public_key))
                result = 1; /* Secret key available.  */