diff options
Diffstat (limited to 'g10/keydb.h')
| -rw-r--r-- | g10/keydb.h | 187 |
1 files changed, 186 insertions, 1 deletions
diff --git a/g10/keydb.h b/g10/keydb.h index 10864509c..a943ded88 100644 --- a/g10/keydb.h +++ b/g10/keydb.h @@ -1,6 +1,7 @@ /* keydb.h - Key database * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, * 2006, 2010 Free Software Foundation, Inc. + * Copyright (C) 2015 g10 Code GmbH * * This file is part of GnuPG. * @@ -132,28 +133,212 @@ union pref_hint #define KEYDB_RESOURCE_FLAG_READONLY 8 /* Open in read only mode. */ #define KEYDB_RESOURCE_FLAG_GPGVDEF 16 /* Default file for gpgv. */ +/* Register a resource (keyring or keybox). The first keyring or + keybox that is added using this function is created if it does not + already exist and the KEYDB_RESOURCE_FLAG_READONLY is not set. + + FLAGS are a combination of the KEYDB_RESOURCE_FLAG_* constants. + + URL must have the following form: + + gnupg-ring:filename = plain keyring + gnupg-kbx:filename = keybox file + filename = check file's type (create as a plain keyring) + + Note: on systems with drive letters (Windows) invalid URLs (i.e., + those with an unrecognized part before the ':' such as "c:\...") + will silently be treated as bare filenames. On other systems, such + URLs will cause this function to return GPG_ERR_GENERAL. + + If KEYDB_RESOURCE_FLAG_DEFAULT is set, the resource is a keyring + and the file ends in ".gpg", then this function also checks if a + file with the same name, but the extension ".kbx" exists, is a + keybox and the OpenPGP flag is set. If so, this function opens + that resource instead. + + If the file is not found, KEYDB_RESOURCE_FLAG_GPGVDEF is set and + the URL ends in ".kbx", then this function will try opening the + same URL, but with the extension ".gpg". If that file is a keybox + with the OpenPGP flag set or it is a keyring, then we use that + instead. + + If the file is not found, KEYDB_RESOURCE_FLAG_DEFAULT is set, the + file should be created and the file's extension is ".gpg" then we + replace the extension with ".kbx". + + + If the KEYDB_RESOURCE_FLAG_PRIMARY is set and the resource is a + keyring (not a keybox), then this resource is considered the + primary resource. This is used by keydb_locate_writable(). If + another primary keyring is set, then that keyring is considered the + primary. + + If KEYDB_RESOURCE_FLAG_READONLY is set and the resource is a + keyring (not a keybox), then the keyring is marked as read only and + operations just as keyring_insert_keyblock will return + GPG_ERR_ACCESS. */ gpg_error_t keydb_add_resource (const char *url, unsigned int flags); -void keydb_dump_stats (void); +/* Dump some statistics to the log. */ +void keydb_dump_stats (void); + +/* Create a new database handle. A database handle is similar to a + file handle: it contains a local file position. This is used when + searching: subsequent searches resume where the previous search + left off. To rewind the position, use keydb_search_reset(). */ KEYDB_HANDLE keydb_new (void); + +/* Free all resources owned by the database handle. */ void keydb_release (KEYDB_HANDLE hd); + +/* Set a flag on the handle to suppress use of cached results. This + is required for updating a keyring and for key listings. Fixme: + Using a new parameter for keydb_new might be a better solution. */ void keydb_disable_caching (KEYDB_HANDLE hd); + +/* Save the last found state and invalidate the current selection + (i.e., the entry selected by keydb_search() is invalidated and + something like keydb_get_keyblock() will return an error). This + does not change the file position. This makes it possible to do + something like: + + keydb_search (hd, ...); // Result 1. + keydb_push_found_state (hd); + keydb_search_reset (hd); + keydb_search (hd, ...); // Result 2. + keydb_pop_found_state (hd); + keydb_get_keyblock (hd, ...); // -> Result 1. + + Note: it is only possible to save a single save state at a time. + In other words, the the save stack only has room for a single + instance of the state. */ void keydb_push_found_state (KEYDB_HANDLE hd); + +/* Restore the previous save state. If the saved state is invalid, + this is equivalent to */ void keydb_pop_found_state (KEYDB_HANDLE hd); + +/* Return the file name of the resource in which the current search + result was found or, if there is no search result, the filename of + the current resource (i.e., the resource that the file position + points to). Note: the filename is not necessarily the URL used to + open it! + + This function only returns NULL if no handle is specified, in all + other error cases an empty string is returned. */ const char *keydb_get_resource_name (KEYDB_HANDLE hd); + +/* Return the keyblock last found by keydb_search() in *RET_KB. + + On success, the function returns 0 and the caller must free *RET_KB + using release_kbnode(). Otherwise, the function returns an error + code. + + The returned keyblock has the kbnode flag bit 0 set for the node + with the public key used to locate the keyblock or flag bit 1 set + for the user ID node. */ gpg_error_t keydb_get_keyblock (KEYDB_HANDLE hd, KBNODE *ret_kb); + +/* Replace the currently selected keyblock (i.e., the last result + returned by keydb_search) with the key block in KB. + + This doesn't do anything if --dry-run was specified. + + Returns 0 on success. Otherwise, it returns an error code. */ gpg_error_t keydb_update_keyblock (KEYDB_HANDLE hd, kbnode_t kb); + +/* Insert a keyblock into one of the underlying keyrings or keyboxes. + + Be default, the keyring / keybox from which the last search result + came is used. If there was no previous search result (or + keydb_search_reset was called), then the keyring / keybox where the + next search would start is used (i.e., the current file position). + + Note: this doesn't do anything if --dry-run was specified. + + Returns 0 on success. Otherwise, it returns an error code. */ gpg_error_t keydb_insert_keyblock (KEYDB_HANDLE hd, kbnode_t kb); + +/* Delete the currently selected keyblock. If you haven't done a + search yet on this database handle (or called keydb_search_reset), + then this will return an error. + + Returns 0 on success or an error code, if an error occurs. */ gpg_error_t keydb_delete_keyblock (KEYDB_HANDLE hd); + +/* A database may consists of multiple keyrings / key boxes. This + sets the "file position" to the start of the first keyring / key + box that is writable (i.e., doesn't have the read-only flag set). + + This first tries the primary keyring (the last keyring (not + keybox!) added using keydb_add_resource() and with + KEYDB_RESOURCE_FLAG_PRIMARY set). If that is not writable, then it + tries the keyrings / keyboxes in the order in which they were + added. */ gpg_error_t keydb_locate_writable (KEYDB_HANDLE hd); + +/* Rebuild the on-disk caches of all key resources. */ void keydb_rebuild_caches (int noisy); + +/* Return the number of skipped blocks (because they were to large to + read from a keybox) since the last search reset. */ unsigned long keydb_get_skipped_counter (KEYDB_HANDLE hd); + +/* Clears the current search result and resets the handle's position + so that the next search starts at the beginning of the database + (the start of the first resource). + + Returns 0 on success and an error code if an error occured. + (Currently, this function always returns 0 if HD is valid.) */ gpg_error_t keydb_search_reset (KEYDB_HANDLE hd); + +/* Search the database for keys matching the search description. + + DESC is an array of search terms with NDESC entries. The search + terms are or'd together. That is, the next entry in the DB that + matches any of the descriptions will be returned. + + Note: this function resumes searching where the last search left + off (i.e., at the current file position). If you want to search + from the start of the database, then you need to first call + keydb_search_reset(). + + If no key matches the search description, returns + GPG_ERR_NOT_FOUND. If there was a match, returns 0. If an error + occured, returns an error code. + + The returned key is considered to be selected and the raw data can, + for instance, be returned by calling keydb_get_keyblock(). */ gpg_error_t keydb_search (KEYDB_HANDLE hd, KEYDB_SEARCH_DESC *desc, size_t ndesc, size_t *descindex); + +/* Return the first non-legacy key in the database. + + If you want the very first key in the database, you can directly + call keydb_search with the search description + KEYDB_SEARCH_MODE_FIRST. */ gpg_error_t keydb_search_first (KEYDB_HANDLE hd); + +/* Return the next key (not the next matching key!). + + Unlike calling keydb_search with KEYDB_SEARCH_MODE_NEXT, this + function silently skips legacy keys. */ gpg_error_t keydb_search_next (KEYDB_HANDLE hd); + +/* This is a convenience function for searching for keys with a long + key id. + + Note: this function resumes searching where the last search left + off. If you want to search the whole database, then you need to + first call keydb_search_reset(). */ gpg_error_t keydb_search_kid (KEYDB_HANDLE hd, u32 *kid); + +/* This is a convenience function for searching for keys with a long + (20 byte) fingerprint. This function ignores legacy keys. + + Note: this function resumes searching where the last search left + off. If you want to search the whole database, then you need to + first call keydb_search_reset(). */ gpg_error_t keydb_search_fpr (KEYDB_HANDLE hd, const byte *fpr); |