[git] GnuPG - branch, master, updated. gnupg-2.1.10-104-g0617a05
by Werner Koch
cvs at cvs.gnupg.org
Mon Jan 11 11:47:27 CET 2016
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "The GNU Privacy Guard".
The branch, master has been updated
via 0617a05eb5cb76b239700355d897eb7b49088bf1 (commit)
via b280aa6423c9492e8c5a9afa57339d06d957996d (commit)
from eb9c021631174fde4c1c444bbc533a7a46d570cd (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 0617a05eb5cb76b239700355d897eb7b49088bf1
Author: Werner Koch <wk at gnupg.org>
Date: Mon Jan 11 11:41:49 2016 +0100
gpg: Move documentation from keydb.h to keydb.c and getkey.c.
--
When using tags (e.g. GNU global) to navigate the source code it is
way easier to have the documentation close to the function we are
looking at. Having the documentation in the header file would require
an extra manual lookup to understand the function.
Signed-off-by: Werner Koch <wk at gnupg.org>
diff --git a/g10/getkey.c b/g10/getkey.c
index 1df7287..d6e27e6 100644
--- a/g10/getkey.c
+++ b/g10/getkey.c
@@ -155,7 +155,18 @@ print_stats ()
#endif
-/* For documentation see keydb.h. */
+/* Cache a copy of a public key in the public key cache. PK is not
+ * cached if caching is disabled (via getkey_disable_caches), if
+ * PK->FLAGS.DONT_CACHE is set, we don't know how to derive a key id
+ * from the public key (e.g., unsupported algorithm), or a key with
+ * the key id is already in the cache.
+ *
+ * The public key packet is copied into the cache using
+ * copy_public_key. Thus, any secret parts are not copied, for
+ * instance.
+ *
+ * This cache is filled by get_pubkey and is read by get_pubkey and
+ * get_pubkey_fast. */
void
cache_public_key (PKT_public_key * pk)
{
@@ -344,7 +355,9 @@ cache_user_id (KBNODE keyblock)
}
-/* For documentation see keydb.h. */
+/* Disable and drop the public key cache (which is filled by
+ cache_public_key and get_pubkey). Note: there is currently no way
+ to reenable this cache. */
void
getkey_disable_caches ()
{
@@ -653,7 +666,27 @@ pk_from_block (GETKEY_CTX ctx, PKT_public_key * pk, KBNODE keyblock,
}
-/* For documentation see keydb.h. */
+/* Return the public key with the key id KEYID and store it at PK.
+ * The resources in *PK should be released using
+ * release_public_key_parts(). This function also stores a copy of
+ * the public key in the user id cache (see cache_public_key).
+ *
+ * If PK is NULL, this function just stores the public key in the
+ * cache and returns the usual return code.
+ *
+ * PK->REQ_USAGE (which is a mask of PUBKEY_USAGE_SIG,
+ * PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT) is passed through to the
+ * lookup function. If this is non-zero, only keys with the specified
+ * usage will be returned. As such, it is essential that
+ * PK->REQ_USAGE be correctly initialized!
+ *
+ * Returns 0 on success, GPG_ERR_NO_PUBKEY if there is no public key
+ * with the specified key id, or another error code if an error
+ * occurs.
+ *
+ * If the data was not read from the cache, then the self-signed data
+ * has definitely been merged into the public key using
+ * merge_selfsigs. */
int
get_pubkey (PKT_public_key * pk, u32 * keyid)
{
@@ -728,7 +761,16 @@ leave:
}
-/* For documentation see keydb.h. */
+/* Similar to get_pubkey, but it does not take PK->REQ_USAGE into
+ * account nor does it merge in the self-signed data. This function
+ * also only considers primary keys. It is intended to be used as a
+ * quick check of the key to avoid recursion. It should only be used
+ * in very certain cases. Like get_pubkey and unlike any of the other
+ * lookup functions, this function also consults the user id cache
+ * (see cache_public_key).
+ *
+ * Return the public key in *PK. The resources in *PK should be
+ * released using release_public_key_parts(). */
int
get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
{
@@ -795,8 +837,12 @@ get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
}
-/* For documentation see keydb.h. */
-KBNODE
+/* Return the key block for the key with key id KEYID or NULL, if an
+ * error occurs. Use release_kbnode() to release the key block.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs. */
+kbnode_t
get_pubkeyblock (u32 * keyid)
{
struct getkey_ctx_s ctx;
@@ -820,7 +866,23 @@ get_pubkeyblock (u32 * keyid)
}
-/* For documentation see keydb.h. */
+/* Return the public key with the key id KEYID iff the secret key is
+ * available and store it at PK. The resources should be released
+ * using release_public_key_parts().
+ *
+ * Unlike other lookup functions, PK may not be NULL. PK->REQ_USAGE
+ * is passed through to the lookup function and is a mask of
+ * PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. Thus, it
+ * must be valid! If this is non-zero, only keys with the specified
+ * usage will be returned.
+ *
+ * Returns 0 on success. If a public key with the specified key id is
+ * not found or a secret key is not available for that public key, an
+ * error code is returned. Note: this function ignores legacy keys.
+ * An error code is also return if an error occurs.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs. */
gpg_error_t
get_seckey (PKT_public_key *pk, u32 *keyid)
{
@@ -1070,7 +1132,56 @@ key_byname (GETKEY_CTX *retctx, strlist_t namelist,
}
-/* For documentation see keydb.h. */
+/* Find a public key identified by NAME.
+ *
+ * If name appears to be a valid valid RFC822 mailbox (i.e., email
+ * address) and auto key lookup is enabled (no_akl == 0), then the
+ * specified auto key lookup methods (--auto-key-lookup) are used to
+ * import the key into the local keyring. Otherwise, just the local
+ * keyring is consulted.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results. In this case, getkey_end() must be used to free the
+ * search context. If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK. Note: PK->REQ_USAGE must be valid!!! PK->REQ_USAGE is
+ * passed through to the lookup function and is a mask of
+ * PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. If this
+ * is non-zero, only keys with the specified usage will be returned.
+ * Note: The self-signed data has already been merged into the public
+ * key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * NAME is a string, which is turned into a search query using
+ * classify_user_id.
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK. This should be freed using release_kbnode().
+ *
+ * If RET_KDBHD is not NULL, then the new database handle used to
+ * conduct the search is returned in *RET_KDBHD. This can be used to
+ * get subsequent results using keydb_search_next or to modify the
+ * returned record. Note: in this case, no advanced filtering is done
+ * for subsequent results (e.g., PK->REQ_USAGE is not respected).
+ * Unlike RETCTX, this is always returned.
+ *
+ * If INCLUDE_UNUSABLE is set, then unusable keys (see the
+ * documentation for skip_unusable for an exact definition) are
+ * skipped unless they are looked up by key id or by fingerprint.
+ *
+ * If NO_AKL is set, then the auto key locate functionality is
+ * disabled and only the local key ring is considered. Note: the
+ * local key ring is consulted even if local is not in the
+ * --auto-key-locate option list!
+ *
+ * This function returns 0 on success. Otherwise, an error code is
+ * returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found. */
int
get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
const char *name, KBNODE * ret_keyblock,
@@ -1334,11 +1445,34 @@ get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
}
-/* For documentation see keydb.h.
-
- FIXME: We should replace this with the _byname function. This can
- be done by creating a userID conforming to the unified fingerprint
- style. */
+/* Lookup a key with the specified fingerprint.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK. Note: this function does an exact search and thus the
+ * returned public key may be a subkey rather than the primary key.
+ * Note: The self-signed data has already been merged into the public
+ * key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If PK->REQ_USAGE is set, it is used to filter the search results.
+ * (Thus, if PK is not NULL, PK->REQ_USAGE must be valid!!!) See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used.
+ *
+ * If R_KEYBLOCK is not NULL, then the first result's keyblock is
+ * returned in *R_KEYBLOCK. This should be freed using
+ * release_kbnode().
+ *
+ * FPRINT is a byte array whose contents is the fingerprint to use as
+ * the search term. FPRINT_LEN specifies the length of the
+ * fingerprint (in bytes). Currently, only 16 and 20-byte
+ * fingerprints are supported.
+ *
+ * FIXME: We should replace this with the _byname function. This can
+ * be done by creating a userID conforming to the unified fingerprint
+ * style. */
int
get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
const byte * fprint, size_t fprint_len)
@@ -1382,7 +1516,16 @@ get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
}
-/* For documentation see keydb.h. */
+/* This function is similar to get_pubkey_byfprint, but it doesn't
+ * merge the self-signed data into the public key and subkeys or into
+ * the user ids. It also doesn't add the key to the user id cache.
+ * Further, this function ignores PK->REQ_USAGE.
+ *
+ * This function is intended to avoid recursion and, as such, should
+ * only be used in very specific situations.
+ *
+ * Like get_pubkey_byfprint, PK may be NULL. In that case, this
+ * function effectively just checks for the existence of the key. */
int
get_pubkey_byfprint_fast (PKT_public_key * pk,
const byte * fprint, size_t fprint_len)
@@ -1556,7 +1699,30 @@ parse_def_secret_key (ctrl_t ctrl)
return NULL;
}
-/* For documentation see keydb.h. */
+
+/* Look up a secret key.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
+ * set, it is used to filter the search results. See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used. Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If --default-key was set, then the specified key is looked up. (In
+ * this case, the default key is returned even if it is considered
+ * unusable. See the documentation for skip_unusable for exactly what
+ * this means.)
+ *
+ * Otherwise, this initiates a DB scan that returns all keys that are
+ * usable (see previous paragraph for exactly what usable means) and
+ * for which a secret key is available.
+ *
+ * This function returns the first match. Additional results can be
+ * returned using getkey_next. */
gpg_error_t
get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
{
@@ -1577,8 +1743,44 @@ get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
return err;
}
+
+
-/* For documentation see keydb.h. */
+/* Search for keys matching some criteria.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results. In this case, getkey_end() must be used to free the
+ * search context. If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
+ * set, it is used to filter the search results. See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used. Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If NAMES is not NULL, then a search query is constructed using
+ * classify_user_id on each of the strings in the list. (Recall: the
+ * database does an OR of the terms, not an AND.) If NAMES is
+ * NULL, then all results are returned.
+ *
+ * If WANT_SECRET is set, then only keys with an available secret key
+ * (either locally or via key registered on a smartcard) are returned.
+ *
+ * This function does not skip unusable keys (see the documentation
+ * for skip_unusable for an exact definition).
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK. This should be freed using release_kbnode().
+ *
+ * This function returns 0 on success. Otherwise, an error code is
+ * returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found. */
gpg_error_t
getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
strlist_t names, int want_secret, kbnode_t *ret_keyblock)
@@ -1588,7 +1790,46 @@ getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
}
-/* For documentation see keydb.h. */
+/* Search for one key matching some criteria.
+ *
+ * If RETCTX is not NULL, then the constructed context is returned in
+ * *RETCTX so that getpubkey_next can be used to get subsequent
+ * results. In this case, getkey_end() must be used to free the
+ * search context. If RETCTX is not NULL, then RET_KDBHD must be
+ * NULL.
+ *
+ * If PK is not NULL, the public key of the first result is returned
+ * in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
+ * set, it is used to filter the search results. See the
+ * documentation for finish_lookup to understand exactly how this is
+ * used. Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * If NAME is not NULL, then a search query is constructed using
+ * classify_user_id on the string. In this case, even unusable keys
+ * (see the documentation for skip_unusable for an exact definition of
+ * unusable) are returned. Otherwise, if --default-key was set, then
+ * that key is returned (even if it is unusable). If neither of these
+ * conditions holds, then the first usable key is returned.
+ *
+ * If WANT_SECRET is set, then only keys with an available secret key
+ * (either locally or via key registered on a smartcard) are returned.
+ *
+ * This function does not skip unusable keys (see the documentation
+ * for skip_unusable for an exact definition).
+ *
+ * If RET_KEYBLOCK is not NULL, the keyblock is returned in
+ * *RET_KEYBLOCK. This should be freed using release_kbnode().
+ *
+ * This function returns 0 on success. Otherwise, an error code is
+ * returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
+ * (if want_secret is set) is returned if the key is not found.
+ *
+ * FIXME: We also have the get_pubkey_byname function which has a
+ * different semantic. Should be merged with this one. */
gpg_error_t
getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
const char *name, int want_secret, kbnode_t *ret_keyblock)
@@ -1620,7 +1861,22 @@ getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
}
-/* For documentation see keydb.h. */
+/* Return the next search result.
+ *
+ * If PK is not NULL, the public key of the next result is returned in
+ * *PK. Note: The self-signed data has already been merged into the
+ * public key using merge_selfsigs. Free *PK by calling
+ * release_public_key_parts (or, if PK was allocated using xfree, you
+ * can use free_public_key, which calls release_public_key_parts(PK)
+ * and then xfree(PK)).
+ *
+ * RET_KEYBLOCK can be given as NULL; if it is not NULL it the entire
+ * found keyblock wis retruned hich must be released with
+ * release_kbnode. If the function returns an error NULL is stored at
+ * RET_KEYBLOCK.
+ *
+ * The self-signed data has already been merged into the public key
+ * using merge_selfsigs. */
gpg_error_t
getkey_next (getkey_ctx_t ctx, PKT_public_key *pk, kbnode_t *ret_keyblock)
{
@@ -1641,7 +1897,8 @@ getkey_next (getkey_ctx_t ctx, PKT_public_key *pk, kbnode_t *ret_keyblock)
}
-/* For documentation see keydb.h. */
+/* Release any resources used by a key listing context. This must be
+ * called on the context returned by, e.g., getkey_byname. */
void
getkey_end (getkey_ctx_t ctx)
{
@@ -1660,7 +1917,10 @@ getkey_end (getkey_ctx_t ctx)
************* Merging stuff ********************
************************************************/
-/* For documentation see keydb.h. */
+/* Set the mainkey_id fields for all keys in KEYBLOCK. This is
+ * usually done by merge_selfsigs but at some places we only need the
+ * main_kid not a full merge. The function also guarantees that all
+ * pk->keyids are computed. */
void
setup_main_keyids (kbnode_t keyblock)
{
@@ -1689,7 +1949,13 @@ setup_main_keyids (kbnode_t keyblock)
}
-/* For documentation see keydb.h. */
+/* KEYBLOCK corresponds to a public key block. This function merges
+ * much of the information from the self-signed data into the public
+ * key, public subkey and user id data structures. If you use the
+ * high-level search API (e.g., get_pubkey) for looking up key blocks,
+ * then you don't need to call this function. This function is
+ * useful, however, if you change the keyblock, e.g., by adding or
+ * removing a self-signed data packet. */
void
merge_keys_and_selfsig (KBNODE keyblock)
{
@@ -3139,7 +3405,38 @@ found:
}
-/* For documentation see keydb.h. */
+/* Enumerate some secret keys (specifically, those specified with
+ * --default-key and --try-secret-key). Use the following procedure:
+ *
+ * 1) Initialize a void pointer to NULL
+ * 2) Pass a reference to this pointer to this function (content)
+ * and provide space for the secret key (sk)
+ * 3) Call this function as long as it does not return an error (or
+ * until you are done). The error code GPG_ERR_EOF indicates the
+ * end of the listing.
+ * 4) Call this function a last time with SK set to NULL,
+ * so that can free it's context.
+ *
+ * In pseudo-code:
+ *
+ * void *ctx = NULL;
+ * PKT_public_key *sk = xmalloc_clear (sizeof (*sk));
+ *
+ * while ((err = enum_secret_keys (&ctx, sk)))
+ * { // Process SK.
+ * if (done)
+ * break;
+ * free_public_key (sk);
+ * sk = xmalloc_clear (sizeof (*sk));
+ * }
+ *
+ * // Release any resources used by CTX.
+ * enum_secret_keys (&ctx, NULL);
+ * free_public_key (sk);
+ *
+ * if (gpg_err_code (err) != GPG_ERR_EOF)
+ * ; // An error occurred.
+ */
gpg_error_t
enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *sk)
{
@@ -3402,8 +3699,8 @@ get_user_id_byfpr_native (const byte *fpr)
}
-
-/* For documentation see keydb.h. */
+/* Return the database handle used by this context. The context still
+ owns the handle. */
KEYDB_HANDLE
get_ctx_handle (GETKEY_CTX ctx)
{
diff --git a/g10/keydb.c b/g10/keydb.c
index 2150a92..e1814fe 100644
--- a/g10/keydb.c
+++ b/g10/keydb.c
@@ -533,7 +533,52 @@ keydb_search_desc_dump (struct keydb_search_desc *desc)
return xasprintf ("Bad search mode (%d)", desc->mode);
}
}
+
+
+/* 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)
{
@@ -864,6 +909,9 @@ 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)
{
@@ -872,6 +920,14 @@ keydb_disable_caching (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)
{
@@ -985,6 +1041,22 @@ unlock_all (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)
{
@@ -1014,6 +1086,8 @@ keydb_push_found_state (KEYDB_HANDLE hd)
}
+/* Restore the previous save state. If the saved state is NULL or
+ invalid, this is a NOP. */
void
keydb_pop_found_state (KEYDB_HANDLE hd)
{
@@ -1204,6 +1278,15 @@ parse_keyblock_image (iobuf_t iobuf, int pk_no, int uid_no,
}
+/* 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)
{
@@ -1382,6 +1465,21 @@ build_keyblock_image (kbnode_t keyblock, iobuf_t *r_iobuf, u32 **r_sigstatus)
}
+/* Update the keyblock KB (i.e., extract the fingerprint and find the
+ * corresponding keyblock in the keyring).
+ *
+ * This doesn't do anything if --dry-run was specified.
+ *
+ * Returns 0 on success. Otherwise, it returns an error code. Note:
+ * if there isn't a keyblock in the keyring corresponding to KB, then
+ * this function returns GPG_ERR_VALUE_NOT_FOUND.
+ *
+ * This function selects the matching record and modifies the current
+ * file position to point to the record just after the selected entry.
+ * Thus, if you do a subsequent search using HD, you should first do a
+ * keydb_search_reset. Further, if the selected record is important,
+ * you should use keydb_push_found_state and keydb_pop_found_state to
+ * save and restore it. */
gpg_error_t
keydb_update_keyblock (KEYDB_HANDLE hd, kbnode_t kb)
{
@@ -1449,6 +1547,16 @@ 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)
{
@@ -1510,6 +1618,11 @@ 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)
{
@@ -1550,6 +1663,15 @@ 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)
{
@@ -1602,6 +1724,8 @@ keydb_locate_writable (KEYDB_HANDLE hd)
return gpg_error (GPG_ERR_NOT_FOUND);
}
+
+/* Rebuild the on-disk caches of all key resources. */
void
keydb_rebuild_caches (int noisy)
{
@@ -1629,6 +1753,8 @@ 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)
{
@@ -1636,6 +1762,12 @@ 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 occurred.
+ * (Currently, this function always returns 0 if HD is valid.) */
gpg_error_t
keydb_search_reset (KEYDB_HANDLE hd)
{
@@ -1676,6 +1808,24 @@ keydb_search_reset (KEYDB_HANDLE hd)
}
+/* Search the database for keys matching the search description. If
+ * the DB contains any legacy keys, these are silently ignored.
+ *
+ * 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
+ * occurred, 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)
@@ -1827,6 +1977,11 @@ keydb_search (KEYDB_HANDLE hd, KEYDB_SEARCH_DESC *desc,
}
+/* 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)
{
@@ -1843,6 +1998,10 @@ 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)
{
@@ -1853,6 +2012,13 @@ keydb_search_next (KEYDB_HANDLE hd)
return keydb_search (hd, &desc, 1, NULL);
}
+
+/* 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)
{
@@ -1865,6 +2031,13 @@ keydb_search_kid (KEYDB_HANDLE hd, u32 *kid)
return keydb_search (hd, &desc, 1, NULL);
}
+
+/* This is a convenience function for searching for keys with a long
+ * (20 byte) fingerprint.
+ *
+ * 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)
{
diff --git a/g10/keydb.h b/g10/keydb.h
index 41d786c..e679d94 100644
--- a/g10/keydb.h
+++ b/g10/keydb.h
@@ -151,50 +151,7 @@ union pref_hint
the result. */
char *keydb_search_desc_dump (struct keydb_search_desc *desc);
-/* 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. */
+/* Register a resource (keyring or keybox). */
gpg_error_t keydb_add_resource (const char *url, unsigned int flags);
/* Dump some statistics to the log. */
@@ -212,94 +169,28 @@ void keydb_release (KEYDB_HANDLE hd);
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. */
+/* Save the last found state and invalidate the current selection. */
void keydb_push_found_state (KEYDB_HANDLE hd);
-/* Restore the previous save state. If the saved state is invalid,
- this is equivalent to */
+/* Restore the previous save state. */
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. */
+/* Return the file name of the resource. */
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. */
+/* Return the keyblock last found by keydb_search. */
gpg_error_t keydb_get_keyblock (KEYDB_HANDLE hd, KBNODE *ret_kb);
-/* Update the keyblock KB (i.e., extract the fingerprint and find the
- corresponding keyblock in the keyring).
-
- This doesn't do anything if --dry-run was specified.
-
- Returns 0 on success. Otherwise, it returns an error code. Note:
- if there isn't a keyblock in the keyring corresponding to KB, then
- this function returns GPG_ERR_VALUE_NOT_FOUND.
-
- This function selects the matching record and modifies the current
- file position to point to the record just after the selected entry.
- Thus, if you do a subsequent search using HD, you should first do a
- keydb_search_reset. Further, if the selected record is important,
- you should use keydb_push_found_state and keydb_pop_found_state to
- save and restore it. */
+/* Update the keyblock KB. */
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. */
+/* Insert a keyblock into one of the underlying keyrings or keyboxes. */
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. */
+/* Delete the currently selected keyblock. */
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. */
+/* Find the first writable resource. */
gpg_error_t keydb_locate_writable (KEYDB_HANDLE hd);
/* Rebuild the on-disk caches of all key resources. */
@@ -309,62 +200,25 @@ void keydb_rebuild_caches (int noisy);
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 occurred.
- (Currently, this function always returns 0 if HD is valid.) */
+/* Clears the current search result and resets the handle's position. */
gpg_error_t keydb_search_reset (KEYDB_HANDLE hd);
-/* Search the database for keys matching the search description. If
- the DB contains any legacy keys, these are silently ignored.
-
- 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
- occurred, 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(). */
+/* Search the database for keys matching the search description. */
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. */
+/* Return the first non-legacy key in the database. */
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. */
+/* Return the next key (not the next matching key!). */
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(). */
+ key id. */
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.
-
- 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(). */
+ (20 byte) fingerprint. */
gpg_error_t keydb_search_fpr (KEYDB_HANDLE hd, const byte *fpr);
@@ -424,66 +278,22 @@ char *gpg_format_keydesc (PKT_public_key *pk, int mode, int escaped);
/*-- getkey.c --*/
-/* Cache a copy of a public key in the public key cache. PK is not
- cached if caching is disabled (via getkey_disable_caches), if
- PK->FLAGS.DONT_CACHE is set, we don't know how to derive a key id
- from the public key (e.g., unsupported algorithm), or a key with
- the key id is already in the cache.
-
- The public key packet is copied into the cache using
- copy_public_key. Thus, any secret parts are not copied, for
- instance.
-
- This cache is filled by get_pubkey and is read by get_pubkey and
- get_pubkey_fast. */
+/* Cache a copy of a public key in the public key cache. */
void cache_public_key( PKT_public_key *pk );
-/* Disable and drop the public key cache (which is filled by
- cache_public_key and get_pubkey). Note: there is currently no way
- to reenable this cache. */
+/* Disable and drop the public key cache. */
void getkey_disable_caches(void);
-/* Return the public key with the key id KEYID and store it in *PK.
- The resources in *PK should be released using
- release_public_key_parts(). This function also stores a copy of
- the public key in the user id cache (see cache_public_key).
-
- If PK is NULL, this function just stores the public key in the
- cache and returns the usual return code.
-
- PK->REQ_USAGE (which is a mask of PUBKEY_USAGE_SIG,
- PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT) is passed through to the
- lookup function. If this is non-zero, only keys with the specified
- usage will be returned. As such, it is essential that
- PK->REQ_USAGE be correctly initialized!
-
- Returns 0 on success, GPG_ERR_NO_PUBKEY if there is no public key
- with the specified key id, or another error code if an error
- occurs.
-
- If the data was not read from the cache, then the self-signed data
- has definitely been merged into the public key using
- merge_selfsigs. */
+/* Return the public key with the key id KEYID and store it at PK. */
int get_pubkey( PKT_public_key *pk, u32 *keyid );
/* Similar to get_pubkey, but it does not take PK->REQ_USAGE into
account nor does it merge in the self-signed data. This function
- also only considers primary keys. It is intended to be used as a
- quick check of the key to avoid recursion. It should only be used
- in very certain cases. Like get_pubkey and unlike any of the other
- lookup functions, this function also consults the user id cache
- (see cache_public_key).
+ also only considers primary keys. */
+int get_pubkey_fast (PKT_public_key *pk, u32 *keyid);
- Return the public key in *PK. The resources in *PK should be
- released using release_public_key_parts(). */
-int get_pubkey_fast ( PKT_public_key *pk, u32 *keyid );
-
-/* Return the key block for the key with key id KEYID or NULL, if an
- error occurs. Use release_kbnode() to release the key block.
-
- The self-signed data has already been merged into the public key
- using merge_selfsigs. */
-KBNODE get_pubkeyblock( u32 *keyid );
+/* Return the key block for the key with KEYID. */
+kbnode_t get_pubkeyblock (u32 *keyid);
/* A list used by get_pubkeys to gather all of the matches. */
struct pubkey_s
@@ -509,118 +319,24 @@ get_pubkeys (ctrl_t ctrl,
int warn_possibly_ambiguous,
pubkey_t *r_keys);
-/* Find a public key identified by the name NAME.
-
- If name appears to be a valid valid RFC822 mailbox (i.e., email
- address) and auto key lookup is enabled (no_akl == 0), then the
- specified auto key lookup methods (--auto-key-lookup) are used to
- import the key into the local keyring. Otherwise, just the local
- keyring is consulted.
-
-
- If RETCTX is not NULL, then the constructed context is returned in
- *RETCTX so that getpubkey_next can be used to get subsequent
- results. In this case, getkey_end() must be used to free the
- search context. If RETCTX is not NULL, then RET_KDBHD must be
- NULL.
-
- If PK is not NULL, the public key of the first result is returned
- in *PK. Note: PK->REQ_USAGE must be valid!!! PK->REQ_USAGE is
- passed through to the lookup function and is a mask of
- PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. If this
- is non-zero, only keys with the specified usage will be returned.
- Note: The self-signed data has already been merged into the public
- key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- NAME is a string, which is turned into a search query using
- classify_user_id.
-
- If RET_KEYBLOCK is not NULL, the keyblock is returned in
- *RET_KEYBLOCK. This should be freed using release_kbnode().
-
- If RET_KDBHD is not NULL, then the new database handle used to
- conduct the search is returned in *RET_KDBHD. This can be used to
- get subsequent results using keydb_search_next or to modify the
- returned record. Note: in this case, no advanced filtering is done
- for subsequent results (e.g., PK->REQ_USAGE is not respected).
- Unlike RETCTX, this is always returned.
-
- If INCLUDE_UNUSABLE is set, then unusable keys (see the
- documentation for skip_unusable for an exact definition) are
- skipped unless they are looked up by key id or by fingerprint.
-
- If NO_AKL is set, then the auto key locate functionality is
- disabled and only the local key ring is considered. Note: the
- local key ring is consulted even if local is not in the
- --auto-key-locate option list!
-
- This function returns 0 on success. Otherwise, an error code is
- returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
- (if want_secret is set) is returned if the key is not found. */
+/* Find a public key identified by NAME. */
int get_pubkey_byname (ctrl_t ctrl,
GETKEY_CTX *retctx, PKT_public_key *pk,
const char *name,
KBNODE *ret_keyblock, KEYDB_HANDLE *ret_kdbhd,
int include_unusable, int no_akl );
-/* Return the public key with the key id KEYID and store it in *PK.
- The resources should be released using release_public_key_parts().
-
- Unlike other lookup functions, PK may not be NULL. PK->REQ_USAGE
- is passed through to the lookup function and is a mask of
- PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. Thus, it
- must be valid! If this is non-zero, only keys with the specified
- usage will be returned.
-
- Returns 0 on success. If a public key with the specified key id is
- not found or a secret key is not available for that public key, an
- error code is returned. Note: this function ignores legacy keys.
- An error code is also return if an error occurs.
-
- The self-signed data has already been merged into the public key
- using merge_selfsigs. */
+/* Return the public key with the key id KEYID iff the secret key is
+ * available and store it at PK. */
gpg_error_t get_seckey (PKT_public_key *pk, u32 *keyid);
-/* Lookup a key with the specified fingerprint.
-
- If PK is not NULL, the public key of the first result is returned
- in *PK. Note: this function does an exact search and thus the
- returned public key may be a subkey rather than the primary key.
- Note: The self-signed data has already been merged into the public
- key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- If PK->REQ_USAGE is set, it is used to filter the search results.
- (Thus, if PK is not NULL, PK->REQ_USAGE must be valid!!!) See the
- documentation for finish_lookup to understand exactly how this is
- used.
-
- If R_KEYBLOCK is not NULL, then the first result's keyblock is
- returned in *R_KEYBLOCK. This should be freed using
- release_kbnode().
-
- FPRINT is a byte array whose contents is the fingerprint to use as
- the search term. FPRINT_LEN specifies the length of the
- fingerprint (in bytes). Currently, only 16 and 20-byte
- fingerprints are supported. */
+/* Lookup a key with the specified fingerprint. */
int get_pubkey_byfprint (PKT_public_key *pk, kbnode_t *r_keyblock,
const byte *fprint, size_t fprint_len);
/* This function is similar to get_pubkey_byfprint, but it doesn't
merge the self-signed data into the public key and subkeys or into
- the user ids. It also doesn't add the key to the user id cache.
- Further, this function ignores PK->REQ_USAGE.
-
- This function is intended to avoid recursion and, as such, should
- only be used in very specific situations.
-
- Like get_pubkey_byfprint, PK may be NULL. In that case, this
- function effectively just checks for the existence of the key. */
+ the user ids. */
int get_pubkey_byfprint_fast (PKT_public_key *pk,
const byte *fprint, size_t fprint_len);
@@ -632,194 +348,40 @@ int have_secret_key_with_kid (u32 *keyid);
of when the option is given) that is available. */
const char *parse_def_secret_key (ctrl_t ctrl);
-/* Look up a secret key.
-
- If PK is not NULL, the public key of the first result is returned
- in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
- set, it is used to filter the search results. See the
- documentation for finish_lookup to understand exactly how this is
- used. Note: The self-signed data has already been merged into the
- public key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- If --default-key was set, then the specified key is looked up. (In
- this case, the default key is returned even if it is considered
- unusable. See the documentation for skip_unusable for exactly what
- this means.)
-
- Otherwise, this initiates a DB scan that returns all keys that are
- usable (see previous paragraph for exactly what usable means) and
- for which a secret key is available.
-
- This function returns the first match. Additional results can be
- returned using getkey_next. */
+/* Look up a secret key. */
gpg_error_t get_seckey_default (ctrl_t ctrl, PKT_public_key *pk);
-/* Search for keys matching some criteria.
-
- If RETCTX is not NULL, then the constructed context is returned in
- *RETCTX so that getpubkey_next can be used to get subsequent
- results. In this case, getkey_end() must be used to free the
- search context. If RETCTX is not NULL, then RET_KDBHD must be
- NULL.
-
- If PK is not NULL, the public key of the first result is returned
- in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
- set, it is used to filter the search results. See the
- documentation for finish_lookup to understand exactly how this is
- used. Note: The self-signed data has already been merged into the
- public key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- If NAMES is not NULL, then a search query is constructed using
- classify_user_id on each of the strings in the list. (Recall: the
- database does an OR of the terms, not an AND.) If NAMES is
- NULL, then all results are returned.
-
- If WANT_SECRET is set, then only keys with an available secret key
- (either locally or via key registered on a smartcard) are returned.
-
- This function does not skip unusable keys (see the documentation
- for skip_unusable for an exact definition).
-
- If RET_KEYBLOCK is not NULL, the keyblock is returned in
- *RET_KEYBLOCK. This should be freed using release_kbnode().
-
- This function returns 0 on success. Otherwise, an error code is
- returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
- (if want_secret is set) is returned if the key is not found. */
+/* Search for keys matching some criteria. */
gpg_error_t getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
strlist_t names, int want_secret,
kbnode_t *ret_keyblock);
-/* Search for keys matching some criteria.
-
- If RETCTX is not NULL, then the constructed context is returned in
- *RETCTX so that getpubkey_next can be used to get subsequent
- results. In this case, getkey_end() must be used to free the
- search context. If RETCTX is not NULL, then RET_KDBHD must be
- NULL.
-
- If PK is not NULL, the public key of the first result is returned
- in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
- set, it is used to filter the search results. See the
- documentation for finish_lookup to understand exactly how this is
- used. Note: The self-signed data has already been merged into the
- public key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- If NAME is not NULL, then a search query is constructed using
- classify_user_id on the string. In this case, even unusable keys
- (see the documentation for skip_unusable for an exact definition of
- unusable) are returned. Otherwise, if --default-key was set, then
- that key is returned (even if it is unusable). If neither of these
- conditions holds, then the first usable key is returned.
-
- If WANT_SECRET is set, then only keys with an available secret key
- (either locally or via key registered on a smartcard) are returned.
-
- This function does not skip unusable keys (see the documentation
- for skip_unusable for an exact definition).
-
- If RET_KEYBLOCK is not NULL, the keyblock is returned in
- *RET_KEYBLOCK. This should be freed using release_kbnode().
-
- This function returns 0 on success. Otherwise, an error code is
- returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
- (if want_secret is set) is returned if the key is not found.
-
- FIXME: We also have the get_pubkey_byname function which has a
- different semantic. Should be merged with this one. */
+/* Search for one key matching some criteria. */
gpg_error_t getkey_byname (ctrl_t ctrl,
getkey_ctx_t *retctx, PKT_public_key *pk,
const char *name, int want_secret,
kbnode_t *ret_keyblock);
-/* Return the next search result.
-
- If PK is not NULL, the public key of the next result is returned in
- *PK. Note: The self-signed data has already been merged into the
- public key using merge_selfsigs. Free *PK by calling
- release_public_key_parts (or, if PK was allocated using xfree, you
- can use free_public_key, which calls release_public_key_parts(PK)
- and then xfree(PK)).
-
- RET_KEYBLOCK can be given as NULL; if it is not NULL it the entire
- found keyblock wis retruned hich must be released with
- release_kbnode. If the function returns an error NULL is stored at
- RET_KEYBLOCK.
-
- The self-signed data has already been merged into the public key
- using merge_selfsigs. */
+/* Return the next search result. */
gpg_error_t getkey_next (getkey_ctx_t ctx, PKT_public_key *pk,
kbnode_t *ret_keyblock);
-/* Release any resources used by a key listing content. This must be
- called on the context returned by, e.g., getkey_byname. */
+/* Release any resources used by a key listing context. */
void getkey_end (getkey_ctx_t ctx);
/* Return the database handle used by this context. The context still
owns the handle. */
KEYDB_HANDLE get_ctx_handle(GETKEY_CTX ctx);
-/* Enumerate some secret keys (specifically, those specified with
- --default-key and --try-secret-key). Use the following procedure:
-
- 1) Initialize a void pointer to NULL
- 2) Pass a reference to this pointer to this function (content)
- and provide space for the secret key (sk)
- 3) Call this function as long as it does not return an error (or
- until you are done). The error code GPG_ERR_EOF indicates the
- end of the listing.
- 4) Call this function a last time with SK set to NULL,
- so that can free it's context.
-
- In pseudo-code:
-
- void *ctx = NULL;
- PKT_public_key *sk = xmalloc_clear (sizeof (*sk));
- gpg_error_t err;
-
- while ((err = enum_secret_keys (&ctx, sk)))
- {
- // Process SK.
-
- if (done)
- break;
-
- free_public_key (sk);
- sk = xmalloc_clear (sizeof (*sk));
- }
-
- // Release any resources used by CTX.
- enum_secret_keys (&ctx, NULL);
- free_public_key (sk);
-
- if (gpg_err_code (err) != GPG_ERR_EOF)
- ; // An error occurred.
- */
+/* Enumerate some secret keys. */
gpg_error_t enum_secret_keys (ctrl_t ctrl, void **context, PKT_public_key *pk);
-/* Set the mainkey_id fields for all keys in KEYBLOCK. This is
- usually done by merge_selfsigs but at some places we only need the
- main_kid not a full merge. The function also guarantees that all
- pk->keyids are computed. */
+/* Set the mainkey_id fields for all keys in KEYBLOCK. */
void setup_main_keyids (kbnode_t keyblock);
-/* KEYBLOCK corresponds to a public key block. This function merges
- much of the information from the self-signed data into the public
- key, public subkey and user id data structures. If you use the
- high-level search API (e.g., get_pubkey) for looking up key blocks,
- then you don't need to call this function. This function is
- useful, however, if you change the keyblock, e.g., by adding or
- removing a self-signed data packet. */
-void merge_keys_and_selfsig( KBNODE keyblock );
+/* This function merges information from the self-signed data into the
+ data structures. */
+void merge_keys_and_selfsig (kbnode_t keyblock);
char*get_user_id_string_native( u32 *keyid );
char*get_long_user_id_string( u32 *keyid );
commit b280aa6423c9492e8c5a9afa57339d06d957996d
Author: Werner Koch <wk at gnupg.org>
Date: Mon Jan 11 10:59:13 2016 +0100
gpg: Fix NULL de-ref for ambiguous key check in --export-ssh-keys.
* g10/getkey.c: Allow arg RET_KEYBLOCK to be NULL.
--
This change adds the expected behavior for the getkey_next function
to fix this NULL de-ref.
GnuPG-bug-id: 2212
Signed-off-by: Werner Koch <wk at gnupg.org>
diff --git a/g10/getkey.c b/g10/getkey.c
index 37a5b56..1df7287 100644
--- a/g10/getkey.c
+++ b/g10/getkey.c
@@ -3059,6 +3059,9 @@ lookup (getkey_ctx_t ctx, kbnode_t *ret_keyblock, kbnode_t *ret_found_key,
KBNODE keyblock = NULL;
KBNODE found_key = NULL;
+ if (ret_keyblock)
+ *ret_keyblock = NULL;
+
for (;;)
{
rc = keydb_search (ctx->kr_handle, ctx->items, ctx->nitems, NULL);
@@ -3113,7 +3116,8 @@ found:
if (!rc)
{
- *ret_keyblock = keyblock; /* Return the keyblock. */
+ if (ret_keyblock)
+ *ret_keyblock = keyblock; /* Return the keyblock. */
keyblock = NULL;
}
else if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND && no_suitable_key)
diff --git a/g10/keydb.h b/g10/keydb.h
index f99136a..41d786c 100644
--- a/g10/keydb.h
+++ b/g10/keydb.h
@@ -750,6 +750,11 @@ gpg_error_t getkey_byname (ctrl_t ctrl,
can use free_public_key, which calls release_public_key_parts(PK)
and then xfree(PK)).
+ RET_KEYBLOCK can be given as NULL; if it is not NULL it the entire
+ found keyblock wis retruned hich must be released with
+ release_kbnode. If the function returns an error NULL is stored at
+ RET_KEYBLOCK.
+
The self-signed data has already been merged into the public key
using merge_selfsigs. */
gpg_error_t getkey_next (getkey_ctx_t ctx, PKT_public_key *pk,
-----------------------------------------------------------------------
Summary of changes:
g10/getkey.c | 351 ++++++++++++++++++++++++++++++++++++++---
g10/keydb.c | 173 ++++++++++++++++++++
g10/keydb.h | 507 +++++------------------------------------------------------
3 files changed, 536 insertions(+), 495 deletions(-)
hooks/post-receive
--
The GNU Privacy Guard
http://git.gnupg.org
More information about the Gnupg-commits
mailing list