g10/tofu.h

   1 /* tofu.h - TOFU trust model.
   2  * Copyright (C) 2015 g10 Code GmbH
   3  *
   4  * This file is part of GnuPG.
   5  *
   6  * GnuPG is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * GnuPG is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef G10_TOFU_H
  21 #define G10_TOFU_H
  22
  23 #include <config.h>
  24
  25 /* For each binding, we have a trust policy.  */
  26 enum tofu_policy
  27   {
  28     /* This value can be returned by tofu_get_policy to indicate that
  29        there is no policy set for the specified binding.  */
  30     TOFU_POLICY_NONE = 0,
  31
  32     /* We made a default policy decision.  This is only done if there
  33        is no conflict with another binding (that is, the email address
  34        is not part of another known key).  The default policy is
  35        configurable (and specified using: --tofu-default-policy).
  36
  37        Note: when using the default policy, we save TOFU_POLICY_AUTO
  38        with the binding, not the policy that was in effect.  This way,
  39        if the user invokes gpg again, but with a different value for
  40        --tofu-default-policy, a different decision is made.  */
  41     TOFU_POLICY_AUTO = 1,
  42
  43     /* The user explicitly marked the binding as good.  In this case,
  44        we return TRUST_FULLY.  */
  45     TOFU_POLICY_GOOD = 2,
  46
  47     /* The user explicitly marked the binding as unknown.  In this
  48        case, we return TRUST_UNKNOWN.  */
  49     TOFU_POLICY_UNKNOWN = 3,
  50
  51     /* The user explicitly marked the binding as bad.  In this case,
  52        we always return TRUST_NEVER.  */
  53     TOFU_POLICY_BAD = 4,
  54
  55     /* The user deferred a definitive policy decision about the
  56        binding (by selecting accept once or reject once).  The next
  57        time we see this binding, we should ask the user what to
  58        do.  */
  59     TOFU_POLICY_ASK = 5,
  60
  61
  62     /* Privat evalue used only within tofu.c.  */
  63     _tofu_GET_POLICY_ERROR = 100
  64   };
  65
  66
  67 /* Return a string representation of a trust policy.  Returns "???" if
  68    POLICY is not valid.  */
  69 const char *tofu_policy_str (enum tofu_policy policy);
  70
  71 /* Convert a binding policy (e.g., TOFU_POLICY_BAD) to a trust level
  72    (e.g., TRUST_BAD) in light of the current configuration.  */
  73 int tofu_policy_to_trust_level (enum tofu_policy policy);
  74
  75 /* Register the binding <PK, USER_ID> and the signature
  76    described by SIGS_DIGEST and SIG_TIME, which it generated.  Origin
  77    describes where the signed data came from, e.g., "email:claws"
  78    (default: "unknown").  If MAY_ASK is 1, then this function may
  79    interact with the user in the case of a conflict or if the
  80    binding's policy is ask.  This function returns the binding's trust
  81    level.  If an error occurs, it returns TRUST_UNKNOWN.  */
  82 int tofu_register (ctrl_t ctrl, PKT_public_key *pk, const char *user_id,
  83                    const byte *sigs_digest, int sigs_digest_len,
  84                    time_t sig_time, const char *origin, int may_ask);
  85
  86 /* Combine a trust level returned from the TOFU trust model with a
  87    trust level returned by the PGP trust model.  This is primarily of
  88    interest when the trust model is tofu+pgp (TM_TOFU_PGP).  */
  89 int tofu_wot_trust_combine (int tofu, int wot);
  90
  91 /* Determine the validity (TRUST_NEVER, etc.) of the binding
  92    <PK, USER_ID>.  If MAY_ASK is 1, then this function may
  93    interact with the user.  If not, TRUST_UNKNOWN is returned.  If an
  94    error occurs, TRUST_UNDEFINED is returned.  */
  95 int tofu_get_validity (ctrl_t ctrl,
  96                        PKT_public_key *pk, const char *user_id, int may_ask);
  97
  98 /* Set the policy for all non-revoked user ids in the keyblock KB to
  99    POLICY.  */
 100 gpg_error_t tofu_set_policy (ctrl_t ctrl, kbnode_t kb, enum tofu_policy policy);
 101
 102 /* Set the TOFU policy for all non-revoked users in the key with the
 103    key id KEYID to POLICY.  */
 104 gpg_error_t tofu_set_policy_by_keyid (ctrl_t ctrl,
 105                                       u32 *keyid, enum tofu_policy policy);
 106
 107 /* Return the TOFU policy for the specified binding in *POLICY.  */
 108 gpg_error_t tofu_get_policy (ctrl_t ctrl,
 109                              PKT_public_key *pk, PKT_user_id *user_id,
 110                              enum tofu_policy *policy);
 111
 112 /* When doing a lot of DB activities (in particular, when listing
 113    keys), this causes the DB to enter batch mode, which can
 114    significantly speed up operations.  */
 115 void tofu_begin_batch_update (void);
 116 void tofu_end_batch_update (void);
 117
 118 /* Release all of the resources associated with a DB meta-handle.  */
 119 void tofu_closedbs (ctrl_t ctrl);
 120
 121 #endif /*G10_TOFU_H*/