mirror of
git://git.gnupg.org/gnupg.git
synced 2025-07-02 22:46:30 +02:00
g10: Improve interface documentation of the keydb API.
* g10/keydb.c: Improve code comments and documentation of internal interfaces. Improve documentation of public APIs and move that to... * g10/keydb.h: ... this file. -- Signed-off-by: Neal H. Walfield <neal@g10code.com>.
This commit is contained in:
Neal H. Walfield
parent
efd1ead9e7
commit
360b699e9b
2 changed files with 224 additions and 70 deletions
189
g10/keydb.h
189
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. */
|
||||
|
||||
gpg_error_t keydb_add_resource (const char *url, unsigned int flags);
|
||||
void keydb_dump_stats (void);
|
||||
/* 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);
|
||||
|
||||
/* 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);
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue