pgpkey.h File Reference

PGP key management routines. More...

#include <stdbool.h>
#include "lib.h"

Include dependency graph for pgpkey.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	PgpRing { PGP_PUBRING , PGP_SECRING }
	PGP ring type. More...

Functions
struct Body *	pgp_class_make_key_attachment (void)
	Implements CryptModuleSpecs::pgp_make_key_attachment() -. More...
struct PgpKeyInfo *	pgp_ask_for_key (char *tag, char *whatfor, KeyFlags abilities, enum PgpRing keyring)
	Ask the user for a PGP key. More...
struct PgpKeyInfo *	pgp_getkeybyaddr (struct Address *a, KeyFlags abilities, enum PgpRing keyring, bool oppenc_mode)
	Find a PGP key by address. More...
struct PgpKeyInfo *	pgp_getkeybystr (const char *p, KeyFlags abilities, enum PgpRing keyring)
	Find a PGP key by string. More...
struct PgpKeyInfo *	pgp_principal_key (struct PgpKeyInfo *key)
	Get the main (parent) PGP key. More...
bool	pgp_key_is_valid (struct PgpKeyInfo *k)
	Is a PGP key valid? More...
bool	pgp_id_is_valid (struct PgpUid *uid)
	Is a PGP key valid. More...
bool	pgp_id_is_strong (struct PgpUid *uid)
	Is a PGP key strong? More...

Detailed Description

PGP key management routines.

Authors

• Richard Russon
• Pietro Cerutti

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 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/.

Definition in file pgpkey.h.

Enumeration Type Documentation

PgpRing

enum PgpRing

PGP ring type.

Enumerator
PGP_PUBRING	Public keys.
PGP_SECRING	Secret keys.

Definition at line 37 of file pgpkey.h.

{
  PGP_PUBRING, 
  PGP_SECRING, 
};

Function Documentation

pgp_ask_for_key()

struct PgpKeyInfo * pgp_ask_for_key	(	char *	tag,
		char *	whatfor,
		KeyFlags	abilities,
		enum PgpRing	keyring
	)

Ask the user for a PGP key.

Parameters

tag	Prompt for the user
whatfor	Use for key, e.g. "signing"
abilities	Abilities to match, see KeyFlags
keyring	PGP keyring to use

Return values

ptr	Selected PGP key

Definition at line 179 of file pgpkey.c.

{
  struct PgpKeyInfo *key = NULL;
  struct PgpCache *l = NULL;
  struct Buffer *resp = mutt_buffer_pool_get();
 
  mutt_clear_error();
 
  if (whatfor)
  {
    for (l = id_defaults; l; l = l->next)
    {
      if (mutt_istr_equal(whatfor, l->what))
      {
        mutt_buffer_strcpy(resp, l->dflt);
        break;
      }
    }
  }
 
  while (true)
  {
    mutt_buffer_reset(resp);
    if (mutt_buffer_get_field(tag, resp, MUTT_COMP_NO_FLAGS, false, NULL, NULL, NULL) != 0)
    {
      goto done;
    }
 
    if (whatfor)
    {
      if (l)
        mutt_str_replace(&l->dflt, mutt_buffer_string(resp));
      else
      {
        l = mutt_mem_malloc(sizeof(struct PgpCache));
        l->next = id_defaults;
        id_defaults = l;
        l->what = mutt_str_dup(whatfor);
        l->dflt = mutt_buffer_strdup(resp);
      }
    }
 
    key = pgp_getkeybystr(mutt_buffer_string(resp), abilities, keyring);
    if (key)
      goto done;
 
    mutt_error(_("No matching keys found for \"%s\""), mutt_buffer_string(resp));
  }
 
done:
  mutt_buffer_pool_release(&resp);
  return key;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pgp_getkeybyaddr()

struct PgpKeyInfo * pgp_getkeybyaddr	(	struct Address *	a,
		KeyFlags	abilities,
		enum PgpRing	keyring,
		bool	oppenc_mode
	)

Find a PGP key by address.

Parameters

a	Email address to match
abilities	Abilities to match, see KeyFlags
keyring	PGP keyring to use
oppenc_mode	If true, use opportunistic encryption

Return values

ptr	Matching PGP key

Definition at line 354 of file pgpkey.c.

{
  if (!a)
    return NULL;
 
  struct ListHead hints = STAILQ_HEAD_INITIALIZER(hints);
 
  bool multi = false;
 
  struct PgpKeyInfo *keys = NULL, *k = NULL, *kn = NULL;
  struct PgpKeyInfo *the_strong_valid_key = NULL;
  struct PgpKeyInfo *a_valid_addrmatch_key = NULL;
  struct PgpKeyInfo *matches = NULL;
  struct PgpKeyInfo **last = &matches;
  struct PgpUid *q = NULL;
 
  if (a->mailbox)
    mutt_list_insert_tail(&hints, mutt_str_dup(a->mailbox));
  if (a->personal)
    pgp_add_string_to_hints(a->personal, &hints);
 
  if (!oppenc_mode)
    mutt_message(_("Looking for keys matching \"%s\"..."), a->mailbox);
  keys = pgp_get_candidates(keyring, &hints);
 
  mutt_list_free(&hints);
 
  if (!keys)
    return NULL;
 
  mutt_debug(LL_DEBUG5, "looking for %s <%s>\n", NONULL(a->personal), NONULL(a->mailbox));
 
  for (k = keys; k; k = kn)
  {
    kn = k->next;
 
    mutt_debug(LL_DEBUG5, "  looking at key: %s\n", pgp_keyid(k));
 
    if (abilities && !(k->flags & abilities))
    {
      mutt_debug(LL_DEBUG3, "  insufficient abilities: Has %x, want %x\n", k->flags, abilities);
      continue;
    }
 
    bool match = false; /* any match */
 
    for (q = k->address; q; q = q->next)
    {
      struct AddressList al = TAILQ_HEAD_INITIALIZER(al);
      mutt_addrlist_parse(&al, NONULL(q->addr));
      struct Address *qa = NULL;
      TAILQ_FOREACH(qa, &al, entries)
      {
        PgpKeyValidFlags validity = pgp_id_matches_addr(a, qa, q);
 
        if (validity & PGP_KV_MATCH) /* something matches */
          match = true;
 
        if ((validity & PGP_KV_VALID) && (validity & PGP_KV_ADDR))
        {
          if (validity & PGP_KV_STRONGID)
          {
            if (the_strong_valid_key && (the_strong_valid_key != k))
              multi = true;
            the_strong_valid_key = k;
          }
          else
          {
            a_valid_addrmatch_key = k;
          }
        }
      }
 
      mutt_addrlist_clear(&al);
    }
 
    if (match)
    {
      *last = pgp_principal_key(k);
      kn = pgp_remove_key(&keys, *last);
      last = pgp_get_lastp(k);
    }
  }
 
  pgp_key_free(&keys);
 
  if (matches)
  {
    if (oppenc_mode)
    {
      const bool c_crypt_opportunistic_encrypt_strong_keys =
          cs_subset_bool(NeoMutt->sub, "crypt_opportunistic_encrypt_strong_keys");
      if (the_strong_valid_key)
      {
        pgp_remove_key(&matches, the_strong_valid_key);
        k = the_strong_valid_key;
      }
      else if (a_valid_addrmatch_key && !c_crypt_opportunistic_encrypt_strong_keys)
      {
        pgp_remove_key(&matches, a_valid_addrmatch_key);
        k = a_valid_addrmatch_key;
      }
      else
        k = NULL;
    }
    else if (the_strong_valid_key && !multi)
    {
      /* There was precisely one strong match on a valid ID.
       * Proceed without asking the user.  */
      pgp_remove_key(&matches, the_strong_valid_key);
      k = the_strong_valid_key;
    }
    else
    {
      /* Else: Ask the user.  */
      k = dlg_select_pgp_key(matches, a, NULL);
      if (k)
        pgp_remove_key(&matches, k);
    }
 
    pgp_key_free(&matches);
 
    return k;
  }
 
  return NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pgp_getkeybystr()

struct PgpKeyInfo * pgp_getkeybystr	(	const char *	cp,
		KeyFlags	abilities,
		enum PgpRing	keyring
	)

Find a PGP key by string.

Parameters

cp	String to match, can be empty but cannot be NULL
abilities	Abilities to match, see KeyFlags
keyring	PGP keyring to use

Return values

ptr	Matching PGP key

Definition at line 490 of file pgpkey.c.

{
  struct ListHead hints = STAILQ_HEAD_INITIALIZER(hints);
  struct PgpKeyInfo *keys = NULL;
  struct PgpKeyInfo *matches = NULL;
  struct PgpKeyInfo **last = &matches;
  struct PgpKeyInfo *k = NULL, *kn = NULL;
  struct PgpUid *a = NULL;
  size_t l;
  const char *ps = NULL, *pl = NULL, *pfcopy = NULL, *phint = NULL;
 
  char *p = strdup(cp); // mutt_str_dup converts "" into NULL, see #1809
  l = mutt_str_len(p);
  if ((l > 0) && (p[l - 1] == '!'))
    p[l - 1] = 0;
 
  mutt_message(_("Looking for keys matching \"%s\"..."), p);
 
  pfcopy = crypt_get_fingerprint_or_id(p, &phint, &pl, &ps);
  pgp_add_string_to_hints(phint, &hints);
  keys = pgp_get_candidates(keyring, &hints);
  mutt_list_free(&hints);
 
  for (k = keys; k; k = kn)
  {
    kn = k->next;
    if (abilities && !(k->flags & abilities))
      continue;
 
    /* This shouldn't happen, but keys without any addresses aren't selectable
     * in dlg_select_pgp_key().  */
    if (!k->address)
      continue;
 
    bool match = false;
 
    mutt_debug(LL_DEBUG5, "matching \"%s\" against key %s:\n", p, pgp_long_keyid(k));
 
    if ((*p == '\0') || (pfcopy && mutt_istr_equal(pfcopy, k->fingerprint)) ||
        (pl && mutt_istr_equal(pl, pgp_long_keyid(k))) ||
        (ps && mutt_istr_equal(ps, pgp_short_keyid(k))))
    {
      mutt_debug(LL_DEBUG5, "        match #1\n");
      match = true;
    }
    else
    {
      for (a = k->address; a; a = a->next)
      {
        mutt_debug(LL_DEBUG5, "matching \"%s\" against key %s, \"%s\":\n", p,
                   pgp_long_keyid(k), NONULL(a->addr));
        if (mutt_istr_find(a->addr, p))
        {
          mutt_debug(LL_DEBUG5, "        match #2\n");
          match = true;
          break;
        }
      }
    }
 
    if (match)
    {
      *last = pgp_principal_key(k);
      kn = pgp_remove_key(&keys, *last);
      last = pgp_get_lastp(k);
    }
  }
 
  pgp_key_free(&keys);
 
  if (matches)
  {
    k = dlg_select_pgp_key(matches, NULL, p);
    if (k)
      pgp_remove_key(&matches, k);
    pgp_key_free(&matches);
  }
  else
  {
    k = NULL;
  }
 
  FREE(&pfcopy);
  FREE(&p);
  return k;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pgp_principal_key()

struct PgpKeyInfo * pgp_principal_key

(

struct PgpKeyInfo *

key

)

Get the main (parent) PGP key.

Parameters

key	Key to start with

Return values

ptr

PGP Key

Definition at line 88 of file pgpkey.c.

{
  if (key->flags & KEYFLAG_SUBKEY && key->parent)
    return key->parent;
  return key;
}

Here is the caller graph for this function:

pgp_key_is_valid()

bool pgp_key_is_valid

(

struct PgpKeyInfo *

k

)

Is a PGP key valid?

Parameters

k	Key to examine

Return values

true	Key is valid

Definition at line 100 of file pgpkey.c.

{
  struct PgpKeyInfo *pk = pgp_principal_key(k);
  if (k->flags & KEYFLAG_CANTUSE)
    return false;
  if (pk->flags & KEYFLAG_CANTUSE)
    return false;
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pgp_id_is_valid()

bool pgp_id_is_valid

(

struct PgpUid *

uid

)

Is a PGP key valid.

Parameters

uid	UID of a PGP key

Return values

true	Key is valid

Definition at line 129 of file pgpkey.c.

{
  if (!pgp_key_is_valid(uid->parent))
    return false;
  if (uid->flags & KEYFLAG_CANTUSE)
    return false;
  /* else */
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pgp_id_is_strong()

bool pgp_id_is_strong

(

struct PgpUid *

uid

)

Is a PGP key strong?

Parameters

uid	UID of a PGP key

Return values

true	Key is strong

Definition at line 116 of file pgpkey.c.

{
  if ((uid->trust & 3) < 3)
    return false;
  /* else */
  return true;
}

Here is the caller graph for this function: