keydb.h

   1 /*
   2  * keydb.h - Routines to store and fetch keys.
   3  *
   4  * Copyright 2002-2004 Jonathan McDowell <noodles@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the Free
   8  * Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along with
  16  * this program; if not, write to the Free Software Foundation, Inc., 51
  17  * Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __KEYDB_H__
  21 #define __KEYDB_H__
  22
  23 #include <inttypes.h>
  24
  25 #include "keystructs.h"
  26 #include "ll.h"
  27
  28 /**
  29  *      struct dbfuncs - All of the functions a DB backend exports.
  30  */
  31 struct dbfuncs {
  32 /**
  33  *      initdb - Initialize the key database.
  34  *      @readonly: If we'll only be reading the DB, not writing to it.
  35  *
  36  *      This function should be called before any of the other functions in
  37  *      this file are called in order to allow the DB to be initialized ready
  38  *      for access.
  39  */
  40         void (*initdb)(bool readonly);
  41
  42 /**
  43  *      cleanupdb - De-initialize the key database.
  44  *
  45  *      This function should be called upon program exit to allow the DB to
  46  *      cleanup after itself.
  47  */
  48         void (*cleanupdb)(void);
  49
  50 /**
  51  *      starttrans - Start a transaction.
  52  *
  53  *      Start a transaction. Intended to be used if we're about to perform many
  54  *      operations on the database to help speed it all up, or if we want
  55  *      something to only succeed if all relevant operations are successful.
  56  */
  57         bool (*starttrans)(void);
  58
  59 /**
  60  *      endtrans - End a transaction.
  61  *
  62  *      Ends a transaction.
  63  */
  64         void (*endtrans)(void);
  65
  66 /**
  67  *      fetch_key - Given a keyid fetch the key from storage.
  68  *      @keyid: The keyid to fetch.
  69  *      @publickey: A pointer to a structure to return the key in.
  70  *      @intrans: If we're already in a transaction.
  71  *
  72  *      This function returns a public key from whatever storage mechanism we
  73  *      are using.
  74  *
  75  *      TODO: What about keyid collisions? Should we use fingerprint instead?
  76  */
  77         int (*fetch_key)(uint64_t keyid, struct openpgp_publickey **publickey,
  78                         bool intrans);
  79
  80 /**
  81  *      store_key - Takes a key and stores it.
  82  *      @publickey: A pointer to the public key to store.
  83  *      @intrans: If we're already in a transaction.
  84  *      @update: If true the key exists and should be updated.
  85  *
  86  *      This function stores a public key in whatever storage mechanism we are
  87  *      using. intrans indicates if we're already in a transaction so don't
  88  *      need to start one. update indicates if the key already exists and is
  89  *      just being updated.
  90  *
  91  *      TODO: Do we store multiple keys of the same id? Or only one and replace
  92  *      it?
  93  */
  94         int (*store_key)(struct openpgp_publickey *publickey, bool intrans,
  95                         bool update);
  96
  97 /**
  98  *      delete_key - Given a keyid delete the key from storage.
  99  *      @keyid: The keyid to delete.
 100  *      @intrans: If we're already in a transaction.
 101  *
 102  *      This function deletes a public key from whatever storage mechanism we
 103  *      are using. Returns 0 if the key existed.
 104  */
 105         int (*delete_key)(uint64_t keyid, bool intrans);
 106
 107 /**
 108  *      fetch_key_text - Trys to find the keys that contain the supplied text.
 109  *      @search: The text to search for.
 110  *      @publickey: A pointer to a structure to return the key in.
 111  *
 112  *      This function searches for the supplied text and returns the keys that
 113  *      contain it.
 114  */
 115         int (*fetch_key_text)(const char *search,
 116                         struct openpgp_publickey **publickey);
 117
 118 /**
 119  *      fetch_key_skshash - Tries to find the keys from an SKS hash
 120  *      @hash: The hash to search for.
 121  *      @publickey: A pointer to a structure to return the key in.
 122  *
 123  *      This function looks for the key that is referenced by the supplied
 124  *      SKS hash and returns it.
 125  */
 126         int (*fetch_key_skshash)(const struct skshash *hash,
 127                         struct openpgp_publickey **publickey);
 128
 129 /**
 130  *      update_keys - Takes a list of public keys and updates them in the DB.
 131  *      @keys: The keys to update in the DB.
 132  *      @sendsync: If we should send a keysync mail.
 133  *
 134  *      Takes a list of keys and adds them to the database, merging them with
 135  *      the key in the database if it's already present there. The key list is
 136  *      update to contain the minimum set of updates required to get from what
 137  *      we had before to what we have now (ie the set of data that was added to
 138  *      the DB). Returns the number of entirely new keys added.
 139  *
 140  *      If sendsync is true then we send out a keysync mail to our sync peers
 141  *      with the update.
 142  */
 143         int (*update_keys)(struct openpgp_publickey **keys, bool sendsync);
 144
 145 /**
 146  *      keyid2uid - Takes a keyid and returns the primary UID for it.
 147  *      @keyid: The keyid to lookup.
 148  *
 149  *      This function returns a UID for the given key. Returns NULL if the key
 150  *      isn't found.
 151  */
 152         char * (*keyid2uid)(uint64_t keyid);
 153
 154 /**
 155  *      getkeysigs - Gets a linked list of the signatures on a key.
 156  *      @keyid: The keyid to get the sigs for.
 157  *      @revoked: Is the key revoked?
 158  *
 159  *      This function gets the list of signatures on a key. Used for key
 160  *      indexing and doing stats bits. If revoked is non-NULL then if the key
 161  *      is revoked it's set to true.
 162  */
 163         struct ll * (*getkeysigs)(uint64_t keyid, bool *revoked);
 164
 165 /**
 166  *      cached_getkeysigs - Gets the signatures on a key.
 167  *      @keyid: The key we want the signatures for.
 168  *
 169  *      This function gets the signatures on a key. It's the same as the
 170  *      getkeysigs function above except we use the hash module to cache the
 171  */
 172         struct ll * (*cached_getkeysigs)(uint64_t keyid);
 173
 174 /**
 175  *      getfullkeyid - Maps a 32bit key id to a 64bit one.
 176  *      @keyid: The 32bit keyid.
 177  *
 178  *      This function maps a 32bit key id to the full 64bit one. It returns the
 179  *      full keyid. If the key isn't found a keyid of 0 is returned.
 180  */
 181         uint64_t (*getfullkeyid)(uint64_t keyid);
 182
 183 /**
 184  *      iterate_keys - call a function once for each key in the db.
 185  *      @iterfunc: The function to call.
 186  *      @ctx: A context pointer
 187  *
 188  *      Calls iterfunc once for each key in the database. ctx is passed
 189  *      unaltered to iterfunc. This function is intended to aid database dumps
 190  *      and statistic calculations.
 191  *
 192  *      Returns the number of keys we iterated over.
 193  */
 194         int (*iterate_keys)(void (*iterfunc)(void *ctx,
 195                         struct openpgp_publickey *key), void *ctx);
 196 };
 197
 198 #endif /* __KEYDB_H__ */