gpgv,w32: Fix --status-fd.
[gnupg.git] / g10 / getkey.c
index fe183fa..163ab80 100644 (file)
@@ -1,6 +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, 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"
@@ -36,6 +36,9 @@
 #include "i18n.h"
 #include "keyserver-internal.h"
 #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
+     search or not.  A search that is exact requires that a key or
+     subkey meet all of the specified criteria.  A search that is not
+     exact allows selecting a different key or subkey from the
+     keyblock that matched the critera.  Further, an exact search
+     returns the key or subkey that matched whereas a non-exact search
+     typically returns the primary key.  See finish_lookup for
+     details.  */
   int exact;
-  int want_secret;       /* The caller requested only secret keys.  */
-  KBNODE keyblock;
-  KBPOS kbpos;
-  KBNODE found_key;     /* Pointer into some keyblock. */
-  strlist_t extra_list;         /* Will be freed when releasing the context.  */
-  int last_rc;
+
+  /* Part of the search criteria: Whether the caller only wants keys
+     with an available secret key.  This is used by getkey_next to get
+     the next result with the same initial criteria.  */
+  int want_secret;
+
+  /* Part of the search criteria: The type of the requested key.  A
+     mask of PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.
+     If non-zero, then for a key to match, it must implement one of
+     the required uses.  */
   int req_usage;
-  int req_algo;
+
+  /* The database handle.  */
   KEYDB_HANDLE kr_handle;
+
+  /* Whether we should call xfree() on the context when the context is
+     released using getkey_end()).  */
   int not_allocated;
+
+  /* This variable is used as backing store for strings which have
+     their address used in ITEMS.  */
+  strlist_t extra_list;
+
+  /* Part of the search criteria: The low-level search specification
+     as passed to keydb_search.  */
   int nitems;
+  /* This must be the last element in the structure.  When we allocate
+     the structure, we allocate it so that ITEMS can hold NITEMS.  */
   KEYDB_SEARCH_DESC items[1];
 };
 
@@ -105,7 +140,14 @@ static user_id_db_t user_id_db;
 static int uid_cache_entries;  /* Number of entries in uid cache. */
 
 static void merge_selfsigs (kbnode_t keyblock);
-static int lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, int want_secret);
+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
@@ -115,7 +157,7 @@ print_stats ()
   for (i = 0; i < DIM (lkup_stats); i++)
     {
       if (lkup_stats[i].any)
-       fprintf (stderr,
+       es_fprintf (es_stderr,
                 "lookup stats: mode=%-2d  ok=%-6d  nokey=%-6d  err=%-6d\n",
                 i,
                 lkup_stats[i].okay_count,
@@ -125,6 +167,18 @@ print_stats ()
 #endif
 
 
+/* 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)
 {
@@ -165,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;
@@ -178,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);
@@ -208,7 +262,7 @@ user_id_not_found_utf8 (void)
 
 /* Return the user ID from the given keyblock.
  * We use the primary uid flag which has been set by the merge_selfsigs
- * function.  The returned value is only valid as long as then given
+ * function.  The returned value is only valid as long as the given
  * keyblock is not changed.  */
 static const char *
 get_primary_uid (KBNODE keyblock, size_t * uidlen)
@@ -269,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))
@@ -312,6 +367,9 @@ cache_user_id (KBNODE keyblock)
 }
 
 
+/* 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 ()
 {
@@ -334,20 +392,310 @@ getkey_disable_caches ()
 }
 
 
+void
+pubkey_free (pubkey_t key)
+{
+  if (key)
+    {
+      xfree (key->pk);
+      release_kbnode (key->keyblock);
+      xfree (key);
+    }
+}
+
+void
+pubkeys_free (pubkey_t keys)
+{
+  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;
+}
+
+
 static void
-pk_from_block (GETKEY_CTX ctx, PKT_public_key * pk, KBNODE keyblock)
+pk_from_block (PKT_public_key *pk, kbnode_t keyblock, kbnode_t found_key)
 {
-  KBNODE a = ctx->found_key ? ctx->found_key : keyblock;
+  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);
 }
 
-/* Get a public key and store it into the allocated pk can be called
- * with PK set to NULL to just read it into some internal
- * structures.  */
+
+/* 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)
 {
@@ -364,6 +712,8 @@ get_pubkey (PKT_public_key * pk, u32 * keyid)
       for (ce = pk_cache; ce; ce = ce->next)
        {
          if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1])
+           /* XXX: We don't check PK->REQ_USAGE here, but if we don't
+              read from the cache, we do check it!  */
            {
              copy_public_key (pk, ce->pk);
              return 0;
@@ -383,28 +733,33 @@ get_pubkey (PKT_public_key * pk, u32 * keyid)
   {
     struct getkey_ctx_s ctx;
     KBNODE kb = NULL;
+    KBNODE found_key = NULL;
     memset (&ctx, 0, sizeof ctx);
     ctx.exact = 1; /* Use the key ID exactly as given.  */
     ctx.not_allocated = 1;
     ctx.kr_handle = keydb_new ();
+    if (!ctx.kr_handle)
+      {
+        rc = gpg_error_from_syserror ();
+        goto leave;
+      }
     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];
-    ctx.req_algo = pk->req_algo;
     ctx.req_usage = pk->req_usage;
-    rc = lookup (&ctx, &kb, 0);
+    rc = lookup (&ctx, &kb, &found_key, 0);
     if (!rc)
       {
-       pk_from_block (&ctx, pk, kb);
+       pk_from_block (pk, kb, found_key);
       }
-    get_pubkey_end (&ctx);
+    getkey_end (&ctx);
     release_kbnode (kb);
   }
   if (!rc)
     goto leave;
 
-  rc = G10ERR_NO_PUBKEY;
+  rc = GPG_ERR_NO_PUBKEY;
 
 leave:
   if (!rc)
@@ -415,10 +770,16 @@ leave:
 }
 
 
-/* Get a public key and store it into the allocated pk.  This function
-   differs from get_pubkey() in that it does not do a check of the key
-   to avoid recursion.  It should be used only in very certain cases.
-   It will only retrieve primary keys.  */
+/* 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)
 {
@@ -427,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 */
@@ -435,7 +796,10 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
 
     for (ce = pk_cache; ce; ce = ce->next)
       {
-       if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1])
+       if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1]
+           /* Only consider primary keys.  */
+           && ce->pk->keyid[0] == ce->pk->main_keyid[0]
+           && ce->pk->keyid[1] == ce->pk->main_keyid[1])
          {
            if (pk)
              copy_public_key (pk, ce->pk);
@@ -446,29 +810,32 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
 #endif
 
   hd = keydb_new ();
+  if (!hd)
+    return gpg_error_from_syserror ();
   rc = keydb_search_kid (hd, keyid);
   if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND)
     {
       keydb_release (hd);
-      return G10ERR_NO_PUBKEY;
+      return GPG_ERR_NO_PUBKEY;
     }
   rc = keydb_get_keyblock (hd, &keyblock);
   keydb_release (hd);
   if (rc)
     {
-      log_error ("keydb_get_keyblock failed: %s\n", g10_errstr (rc));
-      return G10ERR_NO_PUBKEY;
+      log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (rc));
+      return GPG_ERR_NO_PUBKEY;
     }
 
-  assert (keyblock && keyblock->pkt
-          && (keyblock->pkt->pkttype == PKT_PUBLIC_KEY
-              || keyblock->pkt->pkttype == PKT_PUBLIC_SUBKEY));
+  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.  */
   keyid_from_pk (keyblock->pkt->pkt.public_key, pkid);
   if (keyid[0] == pkid[0] && keyid[1] == pkid[1])
     copy_public_key (pk, keyblock->pkt->pkt.public_key);
   else
-    rc = G10ERR_NO_PUBKEY;
+    rc = GPG_ERR_NO_PUBKEY;
 
   release_kbnode (keyblock);
 
@@ -479,7 +846,12 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
 }
 
 
-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;
@@ -490,61 +862,82 @@ get_pubkeyblock (u32 * keyid)
   /* No need to set exact here because we want the entire block.  */
   ctx.not_allocated = 1;
   ctx.kr_handle = keydb_new ();
+  if (!ctx.kr_handle)
+    return NULL;
   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];
-  rc = lookup (&ctx, &keyblock, 0);
-  get_pubkey_end (&ctx);
+  rc = lookup (&ctx, &keyblock, NULL, 0);
+  getkey_end (&ctx);
 
   return rc ? NULL : keyblock;
 }
 
 
-
-
-/*
- * Get a public key and store it into PK.  This functions check that a
- * corresponding secret key is available.  With no secret key it does
- * not succeeed.
- */
+/* 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)
 {
   gpg_error_t err;
   struct getkey_ctx_s ctx;
   kbnode_t keyblock = NULL;
+  kbnode_t found_key = NULL;
 
   memset (&ctx, 0, sizeof ctx);
   ctx.exact = 1; /* Use the key ID exactly as given.  */
   ctx.not_allocated = 1;
   ctx.kr_handle = keydb_new ();
+  if (!ctx.kr_handle)
+    return gpg_error_from_syserror ();
   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];
-  ctx.req_algo = pk->req_algo;
   ctx.req_usage = pk->req_usage;
-  err = lookup (&ctx, &keyblock, 1);
+  err = lookup (&ctx, &keyblock, &found_key, 1);
   if (!err)
     {
-      pk_from_block (&ctx, pk, keyblock);
+      pk_from_block (pk, keyblock, found_key);
     }
-  get_pubkey_end (&ctx);
+  getkey_end (&ctx);
   release_kbnode (keyblock);
 
   if (!err)
-    err = agent_probe_secret_key (/*ctrl*/NULL, pk);
+    {
+      err = agent_probe_secret_key (/*ctrl*/NULL, pk);
+      if (err)
+       release_public_key_parts (pk);
+    }
 
   return err;
 }
 
 
+/* Skip unusable keys.  A key is unusable if it is revoked, expired or
+   disabled or if the selected user id is revoked or expired.  */
 static int
-skip_unusable (void *dummy, u32 * keyid, PKT_user_id * uid)
+skip_unusable (void *dummy, u32 * keyid, int uid_no)
 {
   int unusable = 0;
   KBNODE keyblock;
+  PKT_public_key *pk;
 
   (void) dummy;
 
@@ -555,28 +948,42 @@ skip_unusable (void *dummy, u32 * keyid, PKT_user_id * uid)
       goto leave;
     }
 
-  /* Is the user ID in question revoked/expired? */
-  if (uid)
+  pk = keyblock->pkt->pkt.public_key;
+
+  /* Is the key revoked or expired?  */
+  if (pk->flags.revoked || pk->has_expired)
+    unusable = 1;
+
+  /* Is the user ID in question revoked or expired? */
+  if (!unusable && uid_no)
     {
       KBNODE node;
+      int uids_seen = 0;
 
       for (node = keyblock; node; node = node->next)
        {
          if (node->pkt->pkttype == PKT_USER_ID)
            {
-             if (cmp_user_ids (uid, node->pkt->pkt.user_id) == 0
-                 && (node->pkt->pkt.user_id->is_revoked
-                     || node->pkt->pkt.user_id->is_expired))
-               {
-                 unusable = 1;
-                 break;
-               }
+             PKT_user_id *user_id = node->pkt->pkt.user_id;
+
+             uids_seen ++;
+             if (uids_seen != uid_no)
+               continue;
+
+             if (user_id->is_revoked || user_id->is_expired)
+               unusable = 1;
+
+             break;
            }
        }
+
+      /* If UID_NO is non-zero, then the keyblock better have at least
+        that many UIDs.  */
+      log_assert (uids_seen == uid_no);
     }
 
   if (!unusable)
-    unusable = pk_is_disabled (keyblock->pkt->pkt.public_key);
+    unusable = pk_is_disabled (pk);
 
 leave:
   release_kbnode (keyblock);
@@ -584,13 +991,48 @@ leave:
 }
 
 
-/* Try to get the pubkey by the userid.  This function looks for the
- * first pubkey certificate which has the given name in a user_id.  If
- * PK has the pubkey algo set, the function will only return a pubkey
- * with that algo.  If NAMELIST is NULL, the first key is returned.
- * The caller should provide storage for the PK or pass NULL if it is
- * not needed.  If RET_KB is not NULL the function stores the entire
- * keyblock at that address.  */
+/* 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 NAMELIST 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 NAMELIST is
+   NULL, then all results are returned.
+
+   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 WANT_SECRET is set, then only keys with an available secret key
+   (either locally or via key registered on a smartcard) are 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 RET_KB is not NULL, the keyblock is returned in *RET_KB.  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.  Note: in this
+   case, no advanced filtering is done for subsequent results (e.g.,
+   WANT_SECRET and PK->REQ_USAGE are not respected).
+
+   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.  */
 static int
 key_byname (GETKEY_CTX *retctx, strlist_t namelist,
            PKT_public_key *pk,
@@ -602,18 +1044,20 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
   strlist_t r;
   GETKEY_CTX ctx;
   KBNODE help_kb = NULL;
+  KBNODE found_key = NULL;
 
   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)
     *ret_kdbhd = NULL;
 
   if (!namelist)
+    /* No search terms: iterate over the whole DB.  */
     {
       ctx = xmalloc_clear (sizeof *ctx);
       ctx->nitems = 1;
@@ -627,6 +1071,9 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
       for (n = 0, r = namelist; r; r = r->next)
        n++;
 
+      /* CTX has space for a single search term at the end.  Thus, we
+        need to allocate sizeof *CTX plus (n - 1) sizeof
+        CTX->ITEMS.  */
       ctx = xmalloc_clear (sizeof *ctx + (n - 1) * sizeof ctx->items);
       ctx->nitems = n;
 
@@ -655,19 +1102,25 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
 
   ctx->want_secret = want_secret;
   ctx->kr_handle = keydb_new ();
+  if (!ctx->kr_handle)
+    {
+      rc = gpg_error_from_syserror ();
+      getkey_end (ctx);
+      return rc;
+    }
+
   if (!ret_kb)
     ret_kb = &help_kb;
 
   if (pk)
     {
-      ctx->req_algo = pk->req_algo;
       ctx->req_usage = pk->req_usage;
     }
 
-  rc = lookup (ctx, ret_kb, want_secret);
+  rc = lookup (ctx, ret_kb, &found_key, want_secret);
   if (!rc && pk)
     {
-      pk_from_block (ctx, pk, *ret_kb);
+      pk_from_block (pk, *ret_kb, found_key);
     }
 
   release_kbnode (help_kb);
@@ -681,21 +1134,63 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
          *ret_kdbhd = ctx->kr_handle;
          ctx->kr_handle = NULL;
        }
-      get_pubkey_end (ctx);
+      getkey_end (ctx);
     }
 
   return rc;
 }
 
 
-
-/* Find a public key from NAME and return the keyblock or the key.  If
-   ret_kdb is not NULL, the KEYDB handle used to locate this keyblock
-   is returned and the caller is responsible for closing it.  If a key
-   was not found (or if local search has been disabled) and NAME is a
-   valid RFC822 mailbox and --auto-key-locate has been enabled, we try
-   to import the key via the online mechanisms defined by
-   --auto-key-locate.  */
+/* 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,
@@ -708,28 +1203,45 @@ 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;
 
+  /* Does NAME appear to be a mailbox (mail address)?  */
   is_mbox = is_valid_mailbox (name);
 
-  /* Check whether the default local search has been disabled.
-     This is the case if either the "nodefault" or the "local" keyword
-     are in the list of auto key locate mechanisms.
-
-     ANYLOCALFIRST is set if the search order has the local method
-     before any other or if "local" is used first by default.  This
-     makes sure that if a RETCTX is used it gets only set if a local
-     search has precedence over the other search methods and only then
-     a followup call to get_pubkey_next shall succeed.  */
+  /* 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).  */
   if (!no_akl)
     {
+      /* 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)
          {
            nodefault = 1;
            break;
          }
+      /* anylocalfirst is true if "local" appears before any other
+        search methods (except "nodefault").  */
       for (akl = opt.auto_key_locate; akl; akl = akl->next)
        if (akl->type != AKL_NODEFAULT)
          {
@@ -740,15 +1252,26 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
     }
 
   if (!nodefault)
-    anylocalfirst = 1;
+    {
+      /* "nodefault" didn't occur.  Thus, "local" is implicitly the
+       *  first method to try.  */
+      anylocalfirst = 1;
+    }
 
   if (nodefault && is_mbox)
     {
-      /* Nodefault but a mailbox - let the AKL locate the key.  */
-      rc = G10ERR_NO_PUBKEY;
+      /* 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.  */
       add_to_strlist (&namelist, name);
       rc = key_byname (retctx, namelist, pk, 0,
                       include_unusable, ret_keyblock, ret_kdbhd);
@@ -756,13 +1279,17 @@ 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) == G10ERR_NO_PUBKEY && !no_akl && is_mbox)
+  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.  */
       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 = "?";
 
@@ -771,15 +1298,15 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
            case AKL_NODEFAULT:
              /* This is a dummy mechanism.  */
              mechanism = "None";
-             rc = G10ERR_NO_PUBKEY;
+             rc = GPG_ERR_NO_PUBKEY;
              break;
 
            case AKL_LOCAL:
              mechanism = "Local";
-             did_key_byname = 1;
+             did_akl_local = 1;
              if (retctx)
                {
-                 get_pubkey_end (*retctx);
+                 getkey_end (*retctx);
                  *retctx = NULL;
                }
              add_to_strlist (&namelist, name);
@@ -791,7 +1318,7 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
            case AKL_CERT:
              mechanism = "DNS CERT";
              glo_ctrl.in_auto_key_retrieve++;
-             rc = keyserver_import_cert (ctrl, name, &fpr, &fpr_len);
+             rc = keyserver_import_cert (ctrl, name, 0, &fpr, &fpr_len);
              glo_ctrl.in_auto_key_retrieve--;
              break;
 
@@ -802,6 +1329,20 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
              glo_ctrl.in_auto_key_retrieve--;
              break;
 
+           case AKL_DANE:
+             mechanism = "DANE";
+             glo_ctrl.in_auto_key_retrieve++;
+             rc = keyserver_import_cert (ctrl, name, 1, &fpr, &fpr_len);
+             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++;
@@ -811,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);
@@ -825,7 +1366,7 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
              else
                {
                  mechanism = "Unconfigured keyserver";
-                 rc = G10ERR_NO_PUBKEY;
+                 rc = GPG_ERR_NO_PUBKEY;
                }
              break;
 
@@ -844,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;
@@ -867,19 +1408,23 @@ 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)
-           {
-             no_fingerprint = 1;
-             rc = G10ERR_NO_PUBKEY;
+         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)
-           {
+         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)
                {
-                 get_pubkey_end (*retctx);
+                 getkey_end (*retctx);
                  *retctx = NULL;
                }
              rc = key_byname (anylocalfirst ? retctx : NULL,
@@ -893,120 +1438,376 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
                        name, mechanism);
              break;
            }
-         if (rc != G10ERR_NO_PUBKEY || opt.verbose || no_fingerprint)
+         if (gpg_err_code (rc) != GPG_ERR_NO_PUBKEY
+              || opt.verbose || no_fingerprint)
            log_info (_("error retrieving '%s' via %s: %s\n"),
                      name, mechanism,
-                     no_fingerprint ? _("No fingerprint") : g10_errstr (rc));
+                     no_fingerprint ? _("No fingerprint") : gpg_strerror (rc));
        }
     }
 
 
   if (rc && retctx)
     {
-      get_pubkey_end (*retctx);
+      getkey_end (*retctx);
       *retctx = NULL;
     }
 
   if (retctx && *retctx)
     {
-      assert (!(*retctx)->extra_list);
+      log_assert (!(*retctx)->extra_list);
       (*retctx)->extra_list = namelist;
     }
   else
     free_strlist (namelist);
+
   return rc;
 }
 
 
-int
-get_pubkey_bynames (GETKEY_CTX * retctx, PKT_public_key * pk,
-                   strlist_t names, KBNODE * ret_keyblock)
+\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
 {
-  return key_byname (retctx, names, pk, 0, 1, ret_keyblock, NULL);
+  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);
 }
 
-int
-get_pubkey_next (GETKEY_CTX ctx, PKT_public_key * pk, KBNODE * ret_keyblock)
+
+static int
+uid_is_ok (const PKT_public_key *key, const PKT_user_id *uid)
 {
-  return gpg_err_code (getkey_next (ctx, pk, ret_keyblock));
+  return key_is_ok (key) && ! uid->is_revoked;
 }
 
-void
-get_pubkey_end (GETKEY_CTX ctx)
+
+static int
+subkey_is_ok (const PKT_public_key *sub)
 {
-  getkey_end (ctx);
+  return ! sub->flags.revoked && sub->flags.valid && ! sub->flags.disabled;
 }
 
 
-/* Search for a key with the given standard fingerprint.  In contrast
- * to get_pubkey_byfprint we assume a right padded fingerprint of the
- * standard length.  PK may be NULL to only put the result into the
- * internal caches.  */
+/* 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_byfpr (PKT_public_key *pk, const byte *fpr)
+get_pubkey_fromfile (ctrl_t ctrl, PKT_public_key *pk, const char *fname)
 {
   gpg_error_t err;
-  struct getkey_ctx_s ctx;
-  kbnode_t kb = NULL;
+  kbnode_t keyblock;
+  kbnode_t found_key;
+  unsigned int infoflags;
 
-  memset (&ctx, 0, sizeof ctx);
-  ctx.exact = 1;
-  ctx.not_allocated = 1;
-  ctx.kr_handle = keydb_new ();
-  ctx.nitems = 1;
-  ctx.items[0].mode = KEYDB_SEARCH_MODE_FPR;
-  memcpy (ctx.items[0].u.fpr, fpr, MAX_FINGERPRINT_LEN);
-  err = lookup (&ctx, &kb, 0);
-  if (!err && pk)
-    pk_from_block (&ctx, pk, kb);
-  release_kbnode (kb);
-  get_pubkey_end (&ctx);
+  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;
 }
 
 
-/* Search for a key with the given fingerprint.
- * 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,
+get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
                     const byte * fprint, size_t fprint_len)
 {
   int rc;
 
+  if (r_keyblock)
+    *r_keyblock = NULL;
+
   if (fprint_len == 20 || fprint_len == 16)
     {
       struct getkey_ctx_s ctx;
       KBNODE kb = NULL;
+      KBNODE found_key = NULL;
 
       memset (&ctx, 0, sizeof ctx);
       ctx.exact = 1;
       ctx.not_allocated = 1;
       ctx.kr_handle = keydb_new ();
+      if (!ctx.kr_handle)
+        return gpg_error_from_syserror ();
+
       ctx.nitems = 1;
       ctx.items[0].mode = fprint_len == 16 ? KEYDB_SEARCH_MODE_FPR16
        : KEYDB_SEARCH_MODE_FPR20;
       memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
-      rc = lookup (&ctx, &kb, 0);
+      rc = lookup (&ctx, &kb, &found_key, 0);
       if (!rc && pk)
-       pk_from_block (&ctx, pk, kb);
+       pk_from_block (pk, kb, found_key);
+      if (!rc && r_keyblock)
+       {
+         *r_keyblock = kb;
+         kb = NULL;
+       }
       release_kbnode (kb);
-      get_pubkey_end (&ctx);
+      getkey_end (&ctx);
     }
   else
-    rc = G10ERR_GENERAL; /* Oops */
+    rc = GPG_ERR_GENERAL; /* Oops */
   return rc;
 }
 
 
-/* Get a public key and store it into the allocated pk.  This function
-   differs from get_pubkey_byfprint() in that it does not do a check
-   of the key to avoid recursion.  It should be used only in very
-   certain cases.  PK may be NULL to check just for the existance of
-   the key.  */
+/* 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)
@@ -1023,22 +1824,25 @@ get_pubkey_byfprint_fast (PKT_public_key * pk,
     fprbuf[i++] = 0;
 
   hd = keydb_new ();
+  if (!hd)
+    return gpg_error_from_syserror ();
+
   rc = keydb_search_fpr (hd, fprbuf);
   if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND)
     {
       keydb_release (hd);
-      return G10ERR_NO_PUBKEY;
+      return GPG_ERR_NO_PUBKEY;
     }
   rc = keydb_get_keyblock (hd, &keyblock);
   keydb_release (hd);
   if (rc)
     {
-      log_error ("keydb_get_keyblock failed: %s\n", g10_errstr (rc));
-      return G10ERR_NO_PUBKEY;
+      log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (rc));
+      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);
@@ -1049,130 +1853,216 @@ get_pubkey_byfprint_fast (PKT_public_key * pk,
   return 0;
 }
 
-
-/* Search for a key with the given fingerprint and return the
- * complete keyblock which may have more than only this key.   */
-int
-get_keyblock_byfprint (KBNODE * ret_keyblock, const byte * fprint,
-                      size_t fprint_len)
+const char *
+parse_def_secret_key (ctrl_t ctrl)
 {
-  int rc;
+  KEYDB_HANDLE hd = NULL;
+  strlist_t t;
+  static int warned;
 
-  if (fprint_len == 20 || fprint_len == 16)
+  for (t = opt.def_secret_key; t; t = t->next)
     {
-      struct getkey_ctx_s ctx;
-
-      memset (&ctx, 0, sizeof ctx);
-      ctx.not_allocated = 1;
-      ctx.kr_handle = keydb_new ();
-      ctx.nitems = 1;
-      ctx.items[0].mode = (fprint_len == 16
-                           ? KEYDB_SEARCH_MODE_FPR16
-                           : KEYDB_SEARCH_MODE_FPR20);
-      memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
-      rc = lookup (&ctx, ret_keyblock, 0);
-      get_pubkey_end (&ctx);
-    }
-  else
-    rc = G10ERR_GENERAL; /* Oops */
-
-  return rc;
-}
+      gpg_error_t err;
+      KEYDB_SEARCH_DESC desc;
+      KBNODE kb;
+      KBNODE node;
 
+      err = classify_user_id (t->d, &desc, 1);
+      if (err)
+        {
+          log_error (_("secret key \"%s\" not found: %s\n"),
+                     t->d, gpg_strerror (err));
+          if (!opt.quiet)
+            log_info (_("(check argument of option '%s')\n"), "--default-key");
+          continue;
+        }
 
-/* Get a secret key by NAME and store it into PK.  If NAME is NULL use
- * the default key.  This functions checks that a corresponding secret
- * key is available.  With no secret key it does not succeeed. */
-gpg_error_t
-get_seckey_byname (PKT_public_key *pk, const char *name)
-{
-  gpg_error_t err;
-  strlist_t namelist = NULL;
-  int include_unusable = 1;
+      if (! hd)
+        {
+          hd = keydb_new ();
+          if (!hd)
+            return NULL;
+        }
+      else
+        keydb_search_reset (hd);
 
-  /* If we have no name, try to use the default secret key.  If we
-     have no default, we'll use the first usable one. */
 
-  if (!name && opt.def_secret_key && *opt.def_secret_key)
-    add_to_strlist (&namelist, opt.def_secret_key);
-  else if (name)
-    add_to_strlist (&namelist, name);
-  else
-    include_unusable = 0;
+      err = keydb_search (hd, &desc, 1, NULL);
+      if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
+        continue;
 
-  err = key_byname (NULL, namelist, pk, 1, include_unusable, NULL, NULL);
+      if (err)
+        {
+          log_error (_("key \"%s\" not found: %s\n"), t->d, gpg_strerror (err));
+          t = NULL;
+          break;
+        }
 
-  free_strlist (namelist);
+      err = keydb_get_keyblock (hd, &kb);
+      if (err)
+        {
+          log_error (_("error reading keyblock: %s\n"),
+                     gpg_strerror (err));
+          continue;
+        }
 
-  return err;
-}
+      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;
 
-/* Search for a key with the given fingerprint.
- * FIXME:
- * We should replace this with the _byname function.  This can be done
- * by creating a userID conforming to the unified fingerprint style.   */
-gpg_error_t
-get_seckey_byfprint (PKT_public_key *pk, const byte * fprint, size_t fprint_len)
-{
-  gpg_error_t err;
+          /* 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;
+            }
 
-  if (fprint_len == 20 || fprint_len == 16)
-    {
-      struct getkey_ctx_s ctx;
-      kbnode_t kb = NULL;
+          err = agent_probe_secret_key (ctrl, pk);
+          if (! err)
+            /* This is a valid key.  */
+            break;
+        }
+      while ((node = find_next_kbnode (node, PKT_PUBLIC_SUBKEY)));
 
-      memset (&ctx, 0, sizeof ctx);
-      ctx.exact = 1;
-      ctx.not_allocated = 1;
-      ctx.kr_handle = keydb_new ();
-      ctx.nitems = 1;
-      ctx.items[0].mode = fprint_len == 16 ? KEYDB_SEARCH_MODE_FPR16
-       : KEYDB_SEARCH_MODE_FPR20;
-      memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
-      err = lookup (&ctx, &kb, 1);
-      if (!err && pk)
-       pk_from_block (&ctx, pk, kb);
       release_kbnode (kb);
-      get_pubkey_end (&ctx);
+      if (err)
+        {
+          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;
+        }
     }
-  else
-    err = gpg_error (GPG_ERR_BUG);
-  return err;
+
+  if (! warned && opt.def_secret_key && ! t)
+    log_info (_("all values passed to '%s' ignored\n"),
+              "--default-key");
+
+  warned = 1;
+
+  if (hd)
+    keydb_release (hd);
+
+  if (t)
+    return t->d;
+  return NULL;
 }
 
 
-/* Search for a secret key with the given fingerprint and return the
-   complete keyblock which may have more than only this key.  Return
-   an error if no corresponding secret key is available.  */
+/* 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_seckeyblock_byfprint (kbnode_t *ret_keyblock,
-                          const byte *fprint, size_t fprint_len)
+get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
 {
   gpg_error_t err;
-  struct getkey_ctx_s ctx;
+  strlist_t namelist = NULL;
+  int include_unusable = 1;
 
-  if (fprint_len != 20 && fprint_len == 16)
-    return gpg_error (GPG_ERR_BUG);
 
-  memset (&ctx, 0, sizeof ctx);
-  ctx.not_allocated = 1;
-  ctx.kr_handle = keydb_new ();
-  ctx.nitems = 1;
-  ctx.items[0].mode = (fprint_len == 16
-                      ? KEYDB_SEARCH_MODE_FPR16 : KEYDB_SEARCH_MODE_FPR20);
-  memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
-  err = lookup (&ctx, ret_keyblock, 1);
-  get_pubkey_end (&ctx);
+  const char *def_secret_key = parse_def_secret_key (ctrl);
+  if (def_secret_key)
+    add_to_strlist (&namelist, def_secret_key);
+  else
+    include_unusable = 0;
+
+  err = key_byname (NULL, namelist, pk, 1, include_unusable, NULL, NULL);
+
+  free_strlist (namelist);
 
   return err;
 }
 
 
 \f
-/* The new function to return a key.
-   FIXME: Document it.  */
+/* 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)
@@ -1182,33 +2072,60 @@ getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
 }
 
 
-/* Get a key by name and store it into PK if that is not NULL.  If
- * RETCTX is not NULL return the search context which needs to be
- * released by the caller using getkey_end.  If NAME is NULL use the
- * default key (see below).  On success and if RET_KEYBLOCK is not
- * NULL the found keyblock is stored at this address.  WANT_SECRET
- * passed as true requires that a secret key is available for the
- * selected key.
+/* 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 WANT_SECRET is true and NAME is NULL and a default key has been
- * defined that defined key is used.  In all other cases the first
- * available key is used.
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK.  This should be freed using release_kbnode().
  *
- * FIXME: Explain what is up with unusable keys.
+ * 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.
- */
+ * different semantic.  Should be merged with this one.  */
 gpg_error_t
-getkey_byname (getkey_ctx_t *retctx, PKT_public_key *pk,
+getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
                const char *name, int want_secret, kbnode_t *ret_keyblock)
 {
   gpg_error_t err;
   strlist_t namelist = NULL;
   int with_unusable = 1;
+  const char *def_secret_key = NULL;
+
+  if (want_secret && !name)
+    def_secret_key = parse_def_secret_key (ctrl);
 
-  if (want_secret && !name && opt.def_secret_key && *opt.def_secret_key)
-    add_to_strlist (&namelist, opt.def_secret_key);
+  if (want_secret && !name && def_secret_key)
+    add_to_strlist (&namelist, def_secret_key);
   else if (name)
     add_to_strlist (&namelist, name);
   else
@@ -1226,27 +2143,60 @@ getkey_byname (getkey_ctx_t *retctx, PKT_public_key *pk,
 }
 
 
-/* The new function to return the next key.  */
+/* 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
+     won't get the result back from the cache and thus end up in an
+     endless loop.  The endless loop can occur, because the cache is
+     used without respecting the current file pointer!  */
+  keydb_disable_caching (ctx->kr_handle);
+
+  /* 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, ctx->want_secret);
-  if (!rc && pk && ret_keyblock)
-    pk_from_block (ctx, pk, *ret_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;
 }
 
 
-/* The new function to finish a key listing.  */
+/* 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)
 {
   if (ctx)
     {
-      memset (&ctx->kbpos, 0, sizeof ctx->kbpos);
       keydb_release (ctx->kr_handle);
       free_strlist (ctx->extra_list);
       if (!ctx->not_allocated)
@@ -1261,9 +2211,9 @@ getkey_end (getkey_ctx_t ctx)
  ************************************************/
 
 /* 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 but the the full merging.  The function also guarantees
  that all pk->keyids are computed. */
* 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)
 {
@@ -1292,7 +2242,13 @@ setup_main_keyids (kbnode_t keyblock)
 }
 
 
-/* Merge all self-signatures with the keys.  */
+/* 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)
 {
@@ -1367,7 +2323,7 @@ parse_key_usage (PKT_signature * sig)
 
 /* Apply information from SIGNODE (which is the valid self-signature
  * associated with that UID) to the UIDNODE:
- * - wether the UID has been revoked
+ * - weather the UID has been revoked
  * - assumed creation date of the UID
  * - temporary store the keyflags here
  * - temporary store the key expiration time here
@@ -1412,8 +2368,8 @@ fixup_uidnode (KBNODE uidnode, KBNODE signode, u32 keycreated)
 
   /* Ditto for the key expiration.  */
   p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_EXPIRE, NULL);
-  if (p && buffer_to_u32 (p))
-    uid->help_key_expire = keycreated + buffer_to_u32 (p);
+  if (p && buf32_to_u32 (p))
+    uid->help_key_expire = keycreated + buf32_to_u32 (p);
   else
     uid->help_key_expire = 0;
 
@@ -1492,7 +2448,33 @@ sig_to_revoke_info (PKT_signature * sig, struct revoke_info *rinfo)
 }
 
 
-/* Note that R_REVOKED may be set to 0, 1 or 2.  */
+/* Given a keyblock, parse the key block and extract various pieces of
+   information and save them with the primary key packet and the user
+   id packets.  For instance, some information is stored in signature
+   packets.  We find the latest such valid packet (since the user can
+   change that information) and copy its contents into the
+   PKT_public_key.
+
+   Note that R_REVOKED may be set to 0, 1 or 2.
+
+   This function fills in the following fields in the primary key's
+   keyblock:
+
+     main_keyid          (computed)
+     revkey / numrevkeys (derived from self signed key data)
+     flags.valid         (whether we have at least 1 self-sig)
+     flags.maybe_revoked (whether a designed revoked the key, but
+                          we are missing the key to check the sig)
+     selfsigversion      (highest version of any valid self-sig)
+     pubkey_usage        (derived from most recent self-sig or most
+                          recent user id)
+     has_expired         (various sources)
+     expiredate          (various sources)
+
+  See the documentation for fixup_uidnode for how the user id packets
+  are modified.  In addition to that the primary user id's is_primary
+  field is set to 1 and the other user id's is_primary are set to
+  0.  */
 static void
 merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
                     struct revoke_info *rinfo)
@@ -1512,7 +2494,18 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
   *r_revoked = 0;
   memset (rinfo, 0, sizeof (*rinfo));
 
+  /* Section 11.1 of RFC 4880 determines the order of packets within a
+     message.  There are three sections, which must occur in the
+     following order: the public key, the user ids and user attributes
+     and the subkeys.  Within each section, each primary packet (e.g.,
+     a user id packet) is followed by one or more signature packets,
+     which modify that packet.  */
+
+  /* According to Section 11.1 of RFC 4880, the public key must be the
+     first packet.  */
   if (keyblock->pkt->pkttype != PKT_PUBLIC_KEY)
+    /* parse_keyblock_image ensures that the first packet is the
+       public key.  */
     BUG ();
   pk = keyblock->pkt->pkt.public_key;
   keytimestamp = pk->timestamp;
@@ -1530,22 +2523,41 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
       key_expire_seen = 1;
     }
 
-  /* First pass: Find the latest direct key self-signature.  We assume
-   * that the newest one overrides all others.  */
+  /* First pass:
+
+      - Find the latest direct key self-signature.  We assume that the
+        newest one overrides all others.
+
+      - Determine whether the key has been revoked.
+
+      - Gather all revocation keys (unlike other data, we don't just
+        take them from the latest self-signed packet).
 
-  /* In case this key was already merged. */
+      - Determine max (sig[...]->version).
+   */
+
+  /* Reset this in case this key was already merged. */
   xfree (pk->revkey);
   pk->revkey = NULL;
   pk->numrevkeys = 0;
 
   signode = NULL;
   sigdate = 0; /* Helper variable to find the latest signature.  */
-  for (k = keyblock; k && k->pkt->pkttype != PKT_USER_ID; k = k->next)
+
+  /* According to Section 11.1 of RFC 4880, the public key comes first
+     and is immediately followed by any signature packets that modify
+     it.  */
+  for (k = keyblock;
+       k && k->pkt->pkttype != PKT_USER_ID
+        && k->pkt->pkttype != PKT_ATTRIBUTE
+        && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
+       k = k->next)
     {
       if (k->pkt->pkttype == PKT_SIGNATURE)
        {
          PKT_signature *sig = k->pkt->pkt.signature;
          if (sig->keyid[0] == kid[0] && sig->keyid[1] == kid[1])
+           /* Self sig.  */
            {
              if (check_key_signature (keyblock, k, NULL))
                ; /* Signature did not verify.  */
@@ -1565,13 +2577,12 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
                }
              else if (IS_KEY_SIG (sig))
                {
-                 /* Add any revocation keys onto the pk.  This is
-                    particularly interesting since we normally only
-                    get data from the most recent 1F signature, but
-                    you need multiple 1F sigs to properly handle
-                    revocation keys (PGP does it this way, and a
-                    revocation key could be sensitive and hence in a
-                    different signature). */
+                 /* Add the indicated revocations keys from all
+                    signatures not just the latest.  We do this
+                    because you need multiple 1F sigs to properly
+                    handle revocation keys (PGP does it this way, and
+                    a revocation key could be sensitive and hence in
+                    a different signature). */
                  if (sig->revkey)
                    {
                      int i;
@@ -1582,11 +2593,12 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
 
                      for (i = 0; i < sig->numrevkeys; i++)
                        memcpy (&pk->revkey[pk->numrevkeys++],
-                               sig->revkey[i],
+                               &sig->revkey[i],
                                sizeof (struct revocation_key));
                    }
 
                  if (sig->timestamp >= sigdate)
+                   /* This is the latest signature so far.  */
                    {
                      if (sig->flags.expired)
                        ; /* Signature has expired - ignore it.  */
@@ -1605,7 +2617,6 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
     }
 
   /* Remove dupes from the revocation keys.  */
-
   if (pk->revkey)
     {
       int i, j, x, changed = 0;
@@ -1636,6 +2647,8 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
     }
 
   if (signode)
+    /* SIGNODE is the 1F signature packet with the latest creation
+       time.  Extract some information from it.  */
     {
       /* Some information from a direct key signature take precedence
        * over the same information given in UID sigs.  */
@@ -1645,9 +2658,9 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
       key_usage = parse_key_usage (sig);
 
       p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_EXPIRE, NULL);
-      if (p && buffer_to_u32 (p))
+      if (p && buf32_to_u32 (p))
        {
-         key_expire = keytimestamp + buffer_to_u32 (p);
+         key_expire = keytimestamp + buf32_to_u32 (p);
          key_expire_seen = 1;
        }
 
@@ -1680,7 +2693,7 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
                       more revoked than this.  */
                    break;
                  }
-               else if (rc == G10ERR_NO_PUBKEY)
+               else if (gpg_err_code (rc) == GPG_ERR_NO_PUBKEY)
                  pk->flags.maybe_revoked = 1;
 
                /* A failure here means the sig did not verify, was
@@ -1696,18 +2709,30 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
       }
 
   /* Second pass: Look at the self-signature of all user IDs.  */
+
+  /* According to RFC 4880 section 11.1, user id and attribute packets
+     are in the second section, after the public key packet and before
+     the subkey packets.  */
   signode = uidnode = NULL;
   sigdate = 0; /* Helper variable to find the latest signature in one UID. */
   for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY; k = k->next)
     {
-      if (k->pkt->pkttype == PKT_USER_ID)
+      if (k->pkt->pkttype == PKT_USER_ID || k->pkt->pkttype == PKT_ATTRIBUTE)
+       /* New user id packet.  */
        {
          if (uidnode && signode)
+           /* Apply the data from the most recent self-signed packet
+              to the preceding user id packet.  */
            {
              fixup_uidnode (uidnode, signode, keytimestamp);
              pk->flags.valid = 1;
            }
-         uidnode = k;
+         /* Clear SIGNODE.  The only relevant self-signed data for
+            UIDNODE follows it.  */
+         if (k->pkt->pkttype == PKT_USER_ID)
+           uidnode = k;
+         else
+           uidnode = NULL;
          signode = NULL;
          sigdate = 0;
        }
@@ -1721,9 +2746,9 @@ 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 revoced with a key revocation.
+                  * because a key should be revoked with a key revocation.
                   * The reason why we have to allow for that is that at
                   * one time an email address may become invalid but later
                   * the same email address may become valid again (hired,
@@ -1779,7 +2804,7 @@ merge_selfsigs_main (KBNODE keyblock, int *r_revoked,
                     avoid infinite recursion in certain cases.
                     There is no reason to check that an ultimately
                     trusted key is still valid - if it has been
-                    revoked or the user should also renmove the
+                    revoked the user should also remove the
                     ultimate trust flag.  */
                  if (get_pubkey_fast (ultimate_pk, sig->keyid) == 0
                      && check_key_signature2 (keyblock, k, ultimate_pk,
@@ -2000,6 +3025,25 @@ buf_to_sig (const byte * buf, size_t len)
   return sig;
 }
 
+/* Use the self-signed data to fill in various fields in subkeys.
+
+   KEYBLOCK is the whole keyblock.  SUBNODE is the subkey to fill in.
+
+   Sets the following fields on the subkey:
+
+     main_keyid
+     flags.valid        if the subkey has a valid self-sig binding
+     flags.revoked
+     flags.backsig
+     pubkey_usage
+     has_expired
+     expired_date
+
+   On this subkey's most revent valid self-signed packet, the
+   following field is set:
+
+     flags.chosen_selfsig
+  */
 static void
 merge_selfsigs_subkey (KBNODE keyblock, KBNODE subnode)
 {
@@ -2025,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];
 
@@ -2096,8 +3141,8 @@ merge_selfsigs_subkey (KBNODE keyblock, KBNODE subnode)
   subpk->pubkey_usage = key_usage;
 
   p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_EXPIRE, NULL);
-  if (p && buffer_to_u32 (p))
-    key_expire = keytimestamp + buffer_to_u32 (p);
+  if (p && buf32_to_u32 (p))
+    key_expire = keytimestamp + buf32_to_u32 (p);
   else
     key_expire = 0;
   subpk->has_expired = key_expire >= curtime ? 0 : key_expire;
@@ -2170,7 +3215,7 @@ merge_selfsigs_subkey (KBNODE keyblock, KBNODE subnode)
 
       if (backsig)
        {
-         /* At ths point, backsig contains the most recent 0x19 sig.
+         /* At this point, backsig contains the most recent 0x19 sig.
             Let's see if it is good. */
 
          /* 2==valid, 1==invalid, 0==didn't check */
@@ -2185,18 +3230,11 @@ merge_selfsigs_subkey (KBNODE keyblock, KBNODE subnode)
 }
 
 
-/*
- * Merge information from the self-signatures with the key, so that
- * we can later use them more easy.
- * The function works by first applying the self signatures to the
- * primary key and the to each subkey.
- * Here are the rules we use to decide which inormation from which
- * self-signature is used:
- * We check all self signatures or validity and ignore all invalid signatures.
- * All signatures are then ordered by their creation date ....
- * For the primary key:
- *   FIXME the docs
- */
+/* Merge information from the self-signatures with the public key,
+   subkeys and user ids to make using them more easy.
+
+   See documentation for merge_selfsigs_main, merge_selfsigs_subkey
+   and fixup_uidnode for exactly which fields are updated.  */
 static void
 merge_selfsigs (KBNODE keyblock)
 {
@@ -2295,77 +3333,115 @@ merge_selfsigs (KBNODE keyblock)
 
 
 \f
-/* See whether the key fits our requirements and in case we do not
- * request the primary key, select a suitable subkey.
+/* See whether the key satisfies any additional requirements specified
+ * in CTX.  If so, return the node of an appropriate key or subkey.
+ * Otherwise, return NULL if there was no appropriate key.
  *
- * Returns: True when a suitable key has been found.
+ * Note that we do not return a reference, i.e. the result must not be
+ * freed using 'release_kbnode'.
  *
- * We have to distinguish four cases:  FIXME!
- *  1. No usage and no primary key requested
+ * 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
- *     FXME
+ *     FIXME
  *  4. Usage but no primary key requested
  *     FIXME
- * FIXME: Tell what is going to happen here and something about the rationale
- * Note: We don't use this function if no specific usage is requested;
- *       This way the getkey functions can be used for plain key listings.
  *
- * CTX ist the keyblock we are investigating, if FOUNDK is not NULL this
- * is the key we actually found by looking at the keyid or a fingerprint and
- * may either point to the primary or one of the subkeys.  */
-static int
-finish_lookup (GETKEY_CTX ctx)
+ */
+static kbnode_t
+finish_lookup (kbnode_t keyblock, unsigned int req_usage, int want_exact,
+               unsigned int *r_flags)
 {
-  KBNODE keyblock = ctx->keyblock;
-  KBNODE k;
-  KBNODE foundk = NULL;
+  kbnode_t k;
+
+  /* If WANT_EXACT is set, the key or subkey that actually matched the
+     low-level search criteria.  */
+  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);
-  /* 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));
+
   u32 latest_date;
-  KBNODE latest_key;
+  kbnode_t latest_key;
+  PKT_public_key *pk;
+  int req_prim;
   u32 curtime = make_timestamp ();
 
-  assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
+  if (r_flags)
+    *r_flags = 0;
+
+#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)));
 
-  ctx->found_key = NULL;
 
-  if (ctx->exact)
+  log_assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
+
+  /* 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;
            }
        }
     }
 
+  /* Get the user id that matched that low-level search criteria.  */
   for (k = keyblock; k; k = k->next)
     {
       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;
        }
     }
 
-  if (DBG_CACHE)
+  if (DBG_LOOKUP)
     log_debug ("finish_lookup: checking key %08lX (%s)(req_usage=%x)\n",
               (ulong) keyid_from_pk (keyblock->pkt->pkt.public_key, NULL),
               foundk ? "one" : "all", req_usage);
@@ -2378,57 +3454,76 @@ finish_lookup (GETKEY_CTX ctx)
 
   latest_date = 0;
   latest_key = NULL;
-  /* Do not look at subkeys if a certification key is requested.  */
-  if ((!foundk || foundk->pkt->pkttype == PKT_PUBLIC_SUBKEY) && !req_prim)
+  /* 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;
-         nextk = k->next;
+         if (foundk)
+            {
+              /* If FOUNDK is not NULL, then only consider that exact
+                 key, i.e., don't iterate.  */
+              nextk = NULL;
+            }
+         else
+           nextk = k->next;
+
          if (k->pkt->pkttype != PKT_PUBLIC_SUBKEY)
            continue;
-         if (foundk)
-           nextk = NULL; /* what a hack */
+
          pk = k->pkt->pkt.public_key;
-         if (DBG_CACHE)
+         if (DBG_LOOKUP)
            log_debug ("\tchecking subkey %08lX\n",
                       (ulong) keyid_from_pk (pk, NULL));
+
          if (!pk->flags.valid)
            {
-             if (DBG_CACHE)
+             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_CACHE)
+             if (DBG_LOOKUP)
                log_debug ("\tsubkey has been revoked\n");
+              n_revoked_or_expired++;
              continue;
            }
          if (pk->has_expired)
            {
-             if (DBG_CACHE)
+             if (DBG_LOOKUP)
                log_debug ("\tsubkey has expired\n");
+              n_revoked_or_expired++;
              continue;
            }
          if (pk->timestamp > curtime && !opt.ignore_valid_from)
            {
-             if (DBG_CACHE)
+             if (DBG_LOOKUP)
                log_debug ("\tsubkey not yet valid\n");
              continue;
            }
 
-         if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
-           {
-             if (DBG_CACHE)
-               log_debug ("\tusage does not match: want=%x have=%x\n",
-                          req_usage, pk->pubkey_usage);
-             continue;
-           }
-
-         if (DBG_CACHE)
+         if (DBG_LOOKUP)
            log_debug ("\tsubkey might be fine\n");
          /* In case a key has a timestamp of 0 set, we make sure
             that it is used.  A better change would be to compare
@@ -2440,68 +3535,75 @@ finish_lookup (GETKEY_CTX ctx)
              latest_key = k;
            }
        }
+      if (n_subkeys == n_revoked_or_expired && r_flags)
+        *r_flags |= LOOKUP_ALL_SUBKEYS_EXPIRED;
     }
 
-  /* Okay now try the primary key unless we want an exact
-   * key ID match on a subkey */
-  if ((!latest_key && !(ctx->exact && foundk != keyblock)) || req_prim)
+  /* 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 && !want_exact) || foundk == keyblock || req_prim)
     {
-      PKT_public_key *pk;
-      if (DBG_CACHE && !foundk && !req_prim)
+      if (DBG_LOOKUP && !foundk && !req_prim)
        log_debug ("\tno suitable subkeys found - trying primary\n");
       pk = keyblock->pkt->pkt.public_key;
       if (!pk->flags.valid)
        {
-         if (DBG_CACHE)
+         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_CACHE)
+         if (DBG_LOOKUP)
            log_debug ("\tprimary key has been revoked\n");
        }
       else if (pk->has_expired)
        {
-         if (DBG_CACHE)
+         if (DBG_LOOKUP)
            log_debug ("\tprimary key has expired\n");
        }
-      else if (!((pk->pubkey_usage & USAGE_MASK) & req_usage))
-       {
-         if (DBG_CACHE)
-           log_debug ("\tprimary key usage does not match: "
-                      "want=%x have=%x\n", req_usage, pk->pubkey_usage);
-       }
       else /* Okay.  */
        {
-         if (DBG_CACHE)
+         if (DBG_LOOKUP)
            log_debug ("\tprimary key may be used\n");
          latest_key = keyblock;
-         latest_date = pk->timestamp;
        }
     }
 
   if (!latest_key)
     {
-      if (DBG_CACHE)
+      if (DBG_LOOKUP)
        log_debug ("\tno suitable key found -  giving up\n");
-      return 0; /* Not found.  */
+      if (r_flags)
+        *r_flags |= LOOKUP_NOT_SELECTED;
+      return NULL; /* Not found.  */
     }
 
-found:
-  if (DBG_CACHE)
+ 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);
     }
 
-  ctx->found_key = latest_key;
-
   if (latest_key != keyblock && opt.verbose)
     {
       char *tempkeystr =
@@ -2513,96 +3615,189 @@ found:
 
   cache_user_id (keyblock);
 
-  return 1; /* Found.  */
+  return latest_key ? latest_key : keyblock; /* 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);
 }
 
 
-/* The main function to lookup a key.  On success the found keyblock
-   is stored at RET_KEYBLOCK and also in CTX.  If WANT_SECRET is true
-   a corresponding secret key is required.  */
+
+/* A high-level function to lookup keys.
+
+   This function builds on top of the low-level keydb API.  It first
+   searches the database using the description stored in CTX->ITEMS,
+   then it filters the results using CTX and, finally, if WANT_SECRET
+   is set, it ignores any keys for which no secret key is available.
+
+   Unlike the low-level search functions, this function also merges
+   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, 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, int want_secret)
+lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
+       int want_secret)
 {
   int rc;
   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;
 
-  rc = 0;
-  while (!(rc = keydb_search (ctx->kr_handle, ctx->items, ctx->nitems, NULL)))
+  for (;;)
     {
-      /* If we are searching for the first key we have to make sure
-         that the next iteration does not do an implicit reset.
-         This can be triggered by an empty key ring. */
+      rc = keydb_search (ctx->kr_handle, ctx->items, ctx->nitems, NULL);
+      if (rc)
+        break;
+
+      /* If we are iterating over the entire database, then we need to
+        change from KEYDB_SEARCH_MODE_FIRST, which does an implicit
+        reset, to KEYDB_SEARCH_MODE_NEXT, which gets the next
+        record.  */
       if (ctx->nitems && ctx->items->mode == KEYDB_SEARCH_MODE_FIRST)
        ctx->items->mode = KEYDB_SEARCH_MODE_NEXT;
 
-      rc = keydb_get_keyblock (ctx->kr_handle, &ctx->keyblock);
+      rc = keydb_get_keyblock (ctx->kr_handle, &keyblock);
       if (rc)
        {
-         log_error ("keydb_get_keyblock failed: %s\n", g10_errstr (rc));
-         rc = 0;
+         log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (rc));
          goto skip;
        }
 
-      if (want_secret && agent_probe_any_secret_key (NULL, ctx->keyblock))
+      if (want_secret && agent_probe_any_secret_key (NULL, keyblock))
         goto skip; /* No secret key available.  */
 
       /* Warning: node flag bits 0 and 1 should be preserved by
-       * merge_selfsigs.  For secret keys, premerge did tranfer the
-       * keys to the keyblock.  */
-      merge_selfsigs (ctx->keyblock);
-      if (finish_lookup (ctx))
+       * merge_selfsigs.  */
+      merge_selfsigs (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. */
-      release_kbnode (ctx->keyblock);
-      ctx->keyblock = NULL;
+      release_kbnode (keyblock);
+      keyblock = NULL;
+      /* The keyblock cache ignores the current "file position".
+         Thus, if we request the next result and the cache matches
+         (and it will since it is what we just looked for), we'll get
+         the same entry back!  We can avoid this infinite loop by
+         disabling the cache.  */
+      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", g10_errstr (rc));
+    log_error ("keydb_search failed: %s\n", gpg_strerror (rc));
 
   if (!rc)
     {
-      *ret_keyblock = ctx->keyblock; /* Return the keyblock.  */
-      ctx->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? G10ERR_UNU_SECKEY : G10ERR_UNU_PUBKEY;
+    rc = want_secret? GPG_ERR_UNUSABLE_SECKEY : GPG_ERR_UNUSABLE_PUBKEY;
   else if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND)
-    rc = want_secret? G10ERR_NO_SECKEY : G10ERR_NO_PUBKEY;
+    rc = want_secret? GPG_ERR_NO_SECKEY : GPG_ERR_NO_PUBKEY;
+
+  release_kbnode (keyblock);
 
-  release_kbnode (ctx->keyblock);
-  ctx->keyblock = NULL;
+  if (ret_found_key)
+    {
+      if (! rc)
+       *ret_found_key = found_key;
+      else
+       *ret_found_key = NULL;
+    }
 
-  ctx->last_rc = rc;
   return rc;
 }
 
 
-
-
-/*
- * Enumerate certain secret keys.  Caller must use these procedure:
- *  1) create a void pointer and initialize it to NULL
- *  2) pass this void pointer by reference to this function
- *     and provide space for the secret key (pass a buffer for sk)
- *  3) call this function as long as it does not return an error.
- *     The error code GPG_ERR_EOF indicates the end of the listing.
- *  4) Always call this function a last time with SK set to NULL,
+/* 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 (void **context, PKT_public_key *sk)
+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;
@@ -2610,6 +3805,7 @@ enum_secret_keys (void **context, PKT_public_key *sk)
     strlist_t sl;
     kbnode_t keyblock;
     kbnode_t node;
+    getkey_ctx_t ctx;
   } *c = *context;
 
   if (!c)
@@ -2625,6 +3821,7 @@ enum_secret_keys (void **context, PKT_public_key *sk)
     {
       /* Free the context.  */
       release_kbnode (c->keyblock);
+      getkey_end (c->ctx);
       xfree (c);
       *context = NULL;
       return 0;
@@ -2642,11 +3839,11 @@ enum_secret_keys (void **context, PKT_public_key *sk)
           do
             {
               name = NULL;
+              keyblock = NULL;
               switch (c->state)
                 {
                 case 0: /* First try to use the --default-key.  */
-                  if (opt.def_secret_key && *opt.def_secret_key)
-                    name = opt.def_secret_key;
+                  name = parse_def_secret_key (ctrl);
                   c->state = 1;
                   break;
 
@@ -2665,24 +3862,57 @@ enum_secret_keys (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 (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.  */
@@ -2711,34 +3941,69 @@ enum_secret_keys (void **context, PKT_public_key *sk)
 /* Return a string with a printable representation of the user_id.
  * this string must be freed by xfree.   */
 static char *
-get_user_id_string (u32 * keyid)
+get_user_id_string (u32 * keyid, int mode, size_t *r_len)
 {
   user_id_db_t r;
+  keyid_list_t a;
   int pass = 0;
-  /* Try it two times; second pass reads from key resources.  */
+  char *p;
+
+  /* Try it two times; second pass reads from the database.  */
   do
     {
       for (r = user_id_db; r; r = r->next)
        {
-         keyid_list_t a;
          for (a = r->keyids; a; a = a->next)
            {
              if (a->keyid[0] == keyid[0] && a->keyid[1] == keyid[1])
                {
-                 return xasprintf ("%s %.*s", keystr (keyid), r->len, r->name);
+                  if (mode == 2)
+                    {
+                      /* An empty string as user id is possible.  Make
+                         sure that the malloc allocates one byte and
+                         does not bail out.  */
+                      p = xmalloc (r->len? r->len : 1);
+                      memcpy (p, r->name, r->len);
+                      if (r_len)
+                        *r_len = r->len;
+                    }
+                  else
+                    {
+                      if (mode)
+                        p = xasprintf ("%08lX%08lX %.*s",
+                                       (ulong) keyid[0], (ulong) keyid[1],
+                                       r->len, r->name);
+                      else
+                        p = xasprintf ("%s %.*s", keystr (keyid),
+                                       r->len, r->name);
+                      if (r_len)
+                        *r_len = strlen (p);
+                    }
+
+                  return p;
                }
            }
        }
     }
   while (++pass < 2 && !get_pubkey (NULL, keyid));
-  return xasprintf ("%s [?]", keystr (keyid));
+
+  if (mode == 2)
+    p = xstrdup (user_id_not_found_utf8 ());
+  else if (mode)
+    p = xasprintf ("%08lX%08lX [?]", (ulong) keyid[0], (ulong) keyid[1]);
+  else
+    p = xasprintf ("%s [?]", keystr (keyid));
+
+  if (r_len)
+    *r_len = strlen (p);
+  return p;
 }
 
 
 char *
 get_user_id_string_native (u32 * keyid)
 {
-  char *p = get_user_id_string (keyid);
+  char *p = get_user_id_string (keyid, 0, NULL);
   char *p2 = utf8_to_native (p, strlen (p), 0);
   xfree (p);
   return p2;
@@ -2748,65 +4013,18 @@ get_user_id_string_native (u32 * keyid)
 char *
 get_long_user_id_string (u32 * keyid)
 {
-  user_id_db_t r;
-  keyid_list_t a;
-  int pass = 0;
-  /* Try it two times; second pass reads from key resources.  */
-  do
-    {
-      for (r = user_id_db; r; r = r->next)
-       {
-         for (a = r->keyids; a; a = a->next)
-           {
-             if (a->keyid[0] == keyid[0] && a->keyid[1] == keyid[1])
-               {
-                 return xasprintf ("%08lX%08lX %.*s",
-                                    (ulong) keyid[0], (ulong) keyid[1],
-                                    r->len, r->name);
-               }
-           }
-       }
-    }
-  while (++pass < 2 && !get_pubkey (NULL, keyid));
-  return xasprintf ("%08lX%08lX [?]", (ulong) keyid[0], (ulong) keyid[1]);
+  return get_user_id_string (keyid, 1, NULL);
 }
 
 
-/* Please try to use get_user_id_native instead of this one.  */
+/* Please try to use get_user_byfpr instead of this one.  */
 char *
 get_user_id (u32 * keyid, size_t * rn)
 {
-  user_id_db_t r;
-  char *p;
-  int pass = 0;
-
-  /* Try it two times; second pass reads from key resources.  */
-  do
-    {
-      for (r = user_id_db; r; r = r->next)
-       {
-         keyid_list_t a;
-         for (a = r->keyids; a; a = a->next)
-           {
-             if (a->keyid[0] == keyid[0] && a->keyid[1] == keyid[1])
-               {
-                  /* An empty string as user id is possible.  Make
-                     sure that the malloc allocates one byte and does
-                     not bail out.  */
-                 p = xmalloc (r->len? r->len : 1);
-                 memcpy (p, r->name, r->len);
-                 *rn = r->len;
-                 return p;
-               }
-           }
-       }
-    }
-  while (++pass < 2 && !get_pubkey (NULL, keyid));
-  p = xstrdup (user_id_not_found_utf8 ());
-  *rn = strlen (p);
-  return p;
+  return get_user_id_string (keyid, 2, rn);
 }
 
+
 /* Please try to use get_user_id_byfpr_native instead of this one.  */
 char *
 get_user_id_native (u32 * keyid)
@@ -2819,8 +4037,11 @@ get_user_id_native (u32 * keyid)
 }
 
 
-/* Return a user id from the caching by looking it up using the FPR
-   which mustbe of size MAX_FINGERPRINT_LEN.  */
+/* Return the user id for a key designated by its fingerprint, FPR,
+   which must be MAX_FINGERPRINT_LEN bytes in size.  Note: the
+   returned string, which must be freed using xfree, may not be NUL
+   terminated.  To determine the length of the string, you must use
+   *RN.  */
 char *
 get_user_id_byfpr (const byte *fpr, size_t *rn)
 {
@@ -2828,7 +4049,7 @@ get_user_id_byfpr (const byte *fpr, size_t *rn)
   char *p;
   int pass = 0;
 
-  /* Try it two times; second pass reads from key resources.  */
+  /* Try it two times; second pass reads from the database.  */
   do
     {
       for (r = user_id_db; r; r = r->next)
@@ -2849,12 +4070,16 @@ get_user_id_byfpr (const byte *fpr, size_t *rn)
            }
        }
     }
-  while (++pass < 2 && !get_pubkey_byfpr (NULL, fpr));
+  while (++pass < 2
+        && !get_pubkey_byfprint (NULL, NULL, fpr, MAX_FINGERPRINT_LEN));
   p = xstrdup (user_id_not_found_utf8 ());
   *rn = strlen (p);
   return p;
 }
 
+/* Like get_user_id_byfpr, but convert the string to the native
+   encoding.  The returned string needs to be freed.  Unlike
+   get_user_id_byfpr, the returned string is NUL terminated.  */
 char *
 get_user_id_byfpr_native (const byte *fpr)
 {
@@ -2866,7 +4091,8 @@ get_user_id_byfpr_native (const byte *fpr)
 }
 
 
-
+/* Return the database handle used by this context.  The context still
+   owns the handle.  */
 KEYDB_HANDLE
 get_ctx_handle (GETKEY_CTX ctx)
 {
@@ -2876,6 +4102,9 @@ get_ctx_handle (GETKEY_CTX ctx)
 static void
 free_akl (struct akl *akl)
 {
+  if (! akl)
+    return;
+
   if (akl->spec)
     free_keyserver_spec (akl->spec);
 
@@ -2924,15 +4153,15 @@ 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
-#ifdef USE_DNS_PKA
       else if (ascii_strcasecmp (tok, "pka") == 0)
        akl->type = AKL_PKA;
-#endif
-      else if ((akl->spec = parse_keyserver_uri (tok, 1, NULL, 0)))
+      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
        {
@@ -2969,26 +4198,11 @@ parse_auto_key_locate (char *options)
 }
 
 
-/* Return true if a secret key or secret subkey is available for one
-   of the public keys in KEYBLOCK.  */
-int
-have_any_secret_key (ctrl_t ctrl, kbnode_t keyblock)
-{
-  kbnode_t node;
-
-  for (node = keyblock; node; node = node->next)
-    if ((node->pkt->pkttype == PKT_PUBLIC_KEY
-         || node->pkt->pkttype == PKT_PUBLIC_SUBKEY)
-        && !agent_probe_secret_key (ctrl, node->pkt->pkt.public_key))
-      return 1;
-  return 0;
-}
-
-
-/* Return true if a secret key is available for the public key with
- * the given KEYID.  This is just a fast check and does not tell us
- * whether the secret key is valid.  It merely tells os whether there
- * is some secret key.  */
+/* Returns true if a secret key is available for the public key with
+   key id KEYID; returns false if not.  This function ignores legacy
+   keys.  Note: this is just a fast check and does not tell us whether
+   the secret key is valid; this check merely indicates whether there
+   is some secret key with the specified key id.  */
 int
 have_secret_key_with_kid (u32 *keyid)
 {
@@ -3000,37 +4214,46 @@ have_secret_key_with_kid (u32 *keyid)
   int result = 0;
 
   kdbhd = keydb_new ();
+  if (!kdbhd)
+    return 0;
   memset (&desc, 0, sizeof desc);
   desc.mode = KEYDB_SEARCH_MODE_LONG_KID;
   desc.u.kid[0] = keyid[0];
   desc.u.kid[1] = keyid[1];
-  while (!result && !(err = keydb_search (kdbhd, &desc, 1, NULL)))
+  while (!result)
     {
+      err = keydb_search (kdbhd, &desc, 1, NULL);
+      if (err)
+        break;
+
       err = keydb_get_keyblock (kdbhd, &keyblock);
       if (err)
         {
-          log_error (_("error reading keyblock: %s\n"), g10_errstr (err));
+          log_error (_("error reading keyblock: %s\n"), gpg_strerror (err));
           break;
         }
 
       for (node = keyblock; node; node = node->next)
        {
           /* Bit 0 of the flags is set if the search found the key
-             using that key or subkey.  */
+             using that key or subkey.  Note: a search will only ever
+             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;
-                  break;
-                }
+               result = 1; /* Secret key available.  */
+             else
+               result = 0;
+
+             break;
            }
        }
       release_kbnode (keyblock);
     }
+
   keydb_release (kdbhd);
   return result;
 }