g10/keydb.h

   1 /* keydb.h - Key database
   2  * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   3  *               2006, 2010 Free Software Foundation, Inc.
   4  * Copyright (C) 2015 g10 Code GmbH
   5  *
   6  * This file is part of GnuPG.
   7  *
   8  * GnuPG is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 3 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * GnuPG is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #ifndef G10_KEYDB_H
  23 #define G10_KEYDB_H
  24
  25 #include <assuan.h>
  26
  27 #include "types.h"
  28 #include "util.h"
  29 #include "packet.h"
  30
  31 /* What qualifies as a certification (rather than a signature?) */
  32 #define IS_CERT(s)       (IS_KEY_SIG(s) || IS_UID_SIG(s) || IS_SUBKEY_SIG(s) \
  33                          || IS_KEY_REV(s) || IS_UID_REV(s) || IS_SUBKEY_REV(s))
  34 #define IS_SIG(s)        (!IS_CERT(s))
  35 #define IS_KEY_SIG(s)    ((s)->sig_class == 0x1f)
  36 #define IS_UID_SIG(s)    (((s)->sig_class & ~3) == 0x10)
  37 #define IS_SUBKEY_SIG(s) ((s)->sig_class == 0x18)
  38 #define IS_KEY_REV(s)    ((s)->sig_class == 0x20)
  39 #define IS_UID_REV(s)    ((s)->sig_class == 0x30)
  40 #define IS_SUBKEY_REV(s) ((s)->sig_class == 0x28)
  41
  42 struct getkey_ctx_s;
  43 typedef struct getkey_ctx_s *GETKEY_CTX;
  44 typedef struct getkey_ctx_s *getkey_ctx_t;
  45
  46 /****************
  47  * A Keyblock is all packets which form an entire certificate;
  48  * i.e. the public key, certificate, trust packets, user ids,
  49  * signatures, and subkey.
  50  *
  51  * This structure is also used to bind arbitrary packets together.
  52  */
  53
  54 struct kbnode_struct {
  55     KBNODE next;
  56     PACKET *pkt;
  57     int flag;
  58     int private_flag;
  59     ulong recno;  /* used while updating the trustdb */
  60 };
  61
  62 #define is_deleted_kbnode(a)  ((a)->private_flag & 1)
  63 #define is_cloned_kbnode(a)   ((a)->private_flag & 2)
  64
  65
  66 enum resource_type {
  67     rt_UNKNOWN = 0,
  68     rt_RING = 1
  69 };
  70
  71
  72 /****************
  73  * A data structure to hold information about the external position
  74  * of a keyblock.
  75  */
  76 struct keyblock_pos_struct {
  77     int   resno;     /* resource number */
  78     enum resource_type rt;
  79     off_t offset;    /* position information */
  80     unsigned count;  /* length of the keyblock in packets */
  81     iobuf_t  fp;     /* Used by enum_keyblocks. */
  82     int secret;      /* working on a secret keyring */
  83     PACKET *pkt;     /* ditto */
  84     int valid;
  85 };
  86 typedef struct keyblock_pos_struct KBPOS;
  87
  88 /* Structure to hold a couple of public key certificates. */
  89 typedef struct pk_list *PK_LIST;  /* Deprecated. */
  90 typedef struct pk_list *pk_list_t;
  91 struct pk_list
  92 {
  93   PK_LIST next;
  94   PKT_public_key *pk;
  95   int flags; /* flag bit 1==throw_keyid */
  96 };
  97
  98 /* Structure to hold a list of secret key certificates.  */
  99 typedef struct sk_list *SK_LIST;
 100 struct sk_list
 101 {
 102   SK_LIST next;
 103   PKT_public_key *pk;
 104   int mark; /* not used */
 105 };
 106
 107 /* structure to collect all information which can be used to
 108  * identify a public key */
 109 typedef struct pubkey_find_info *PUBKEY_FIND_INFO;
 110 struct pubkey_find_info {
 111     u32  keyid[2];
 112     unsigned nbits;
 113     byte pubkey_algo;
 114     byte fingerprint[MAX_FINGERPRINT_LEN];
 115     char userid[1];
 116 };
 117
 118
 119 typedef struct keydb_handle *KEYDB_HANDLE;
 120
 121
 122 /* Helper type for preference fucntions. */
 123 union pref_hint
 124 {
 125   int digest_length;
 126 };
 127
 128
 129 /*-- keydb.c --*/
 130
 131 #define KEYDB_RESOURCE_FLAG_PRIMARY  2  /* The primary resource.  */
 132 #define KEYDB_RESOURCE_FLAG_DEFAULT  4  /* The default one.  */
 133 #define KEYDB_RESOURCE_FLAG_READONLY 8  /* Open in read only mode.  */
 134 #define KEYDB_RESOURCE_FLAG_GPGVDEF 16  /* Default file for gpgv.  */
 135
 136 /* Register a resource (keyring or keybox).  The first keyring or
 137    keybox that is added using this function is created if it does not
 138    already exist and the KEYDB_RESOURCE_FLAG_READONLY is not set.
 139
 140    FLAGS are a combination of the KEYDB_RESOURCE_FLAG_* constants.
 141
 142    URL must have the following form:
 143
 144      gnupg-ring:filename  = plain keyring
 145      gnupg-kbx:filename   = keybox file
 146      filename             = check file's type (create as a plain keyring)
 147
 148    Note: on systems with drive letters (Windows) invalid URLs (i.e.,
 149    those with an unrecognized part before the ':' such as "c:\...")
 150    will silently be treated as bare filenames.  On other systems, such
 151    URLs will cause this function to return GPG_ERR_GENERAL.
 152
 153    If KEYDB_RESOURCE_FLAG_DEFAULT is set, the resource is a keyring
 154    and the file ends in ".gpg", then this function also checks if a
 155    file with the same name, but the extension ".kbx" exists, is a
 156    keybox and the OpenPGP flag is set.  If so, this function opens
 157    that resource instead.
 158
 159    If the file is not found, KEYDB_RESOURCE_FLAG_GPGVDEF is set and
 160    the URL ends in ".kbx", then this function will try opening the
 161    same URL, but with the extension ".gpg".  If that file is a keybox
 162    with the OpenPGP flag set or it is a keyring, then we use that
 163    instead.
 164
 165    If the file is not found, KEYDB_RESOURCE_FLAG_DEFAULT is set, the
 166    file should be created and the file's extension is ".gpg" then we
 167    replace the extension with ".kbx".
 168
 169
 170    If the KEYDB_RESOURCE_FLAG_PRIMARY is set and the resource is a
 171    keyring (not a keybox), then this resource is considered the
 172    primary resource.  This is used by keydb_locate_writable().  If
 173    another primary keyring is set, then that keyring is considered the
 174    primary.
 175
 176    If KEYDB_RESOURCE_FLAG_READONLY is set and the resource is a
 177    keyring (not a keybox), then the keyring is marked as read only and
 178    operations just as keyring_insert_keyblock will return
 179    GPG_ERR_ACCESS.  */
 180 gpg_error_t keydb_add_resource (const char *url, unsigned int flags);
 181
 182 /* Dump some statistics to the log.  */
 183 void keydb_dump_stats (void);
 184
 185 /* Create a new database handle.  A database handle is similar to a
 186    file handle: it contains a local file position.  This is used when
 187    searching: subsequent searches resume where the previous search
 188    left off.  To rewind the position, use keydb_search_reset().  */
 189 KEYDB_HANDLE keydb_new (void);
 190
 191 /* Free all resources owned by the database handle.  */
 192 void keydb_release (KEYDB_HANDLE hd);
 193
 194 /* Set a flag on the handle to suppress use of cached results.  This
 195    is required for updating a keyring and for key listings.  Fixme:
 196    Using a new parameter for keydb_new might be a better solution.  */
 197 void keydb_disable_caching (KEYDB_HANDLE hd);
 198
 199 /* Save the last found state and invalidate the current selection
 200    (i.e., the entry selected by keydb_search() is invalidated and
 201    something like keydb_get_keyblock() will return an error).  This
 202    does not change the file position.  This makes it possible to do
 203    something like:
 204
 205      keydb_search (hd, ...);  // Result 1.
 206      keydb_push_found_state (hd);
 207        keydb_search_reset (hd);
 208        keydb_search (hd, ...);  // Result 2.
 209      keydb_pop_found_state (hd);
 210      keydb_get_keyblock (hd, ...);  // -> Result 1.
 211
 212    Note: it is only possible to save a single save state at a time.
 213    In other words, the the save stack only has room for a single
 214    instance of the state.  */
 215 void keydb_push_found_state (KEYDB_HANDLE hd);
 216
 217 /* Restore the previous save state.  If the saved state is invalid,
 218    this is equivalent to */
 219 void keydb_pop_found_state (KEYDB_HANDLE hd);
 220
 221 /* Return the file name of the resource in which the current search
 222    result was found or, if there is no search result, the filename of
 223    the current resource (i.e., the resource that the file position
 224    points to).  Note: the filename is not necessarily the URL used to
 225    open it!
 226
 227    This function only returns NULL if no handle is specified, in all
 228    other error cases an empty string is returned.  */
 229 const char *keydb_get_resource_name (KEYDB_HANDLE hd);
 230
 231 /* Return the keyblock last found by keydb_search() in *RET_KB.
 232
 233    On success, the function returns 0 and the caller must free *RET_KB
 234    using release_kbnode().  Otherwise, the function returns an error
 235    code.
 236
 237    The returned keyblock has the kbnode flag bit 0 set for the node
 238    with the public key used to locate the keyblock or flag bit 1 set
 239    for the user ID node.  */
 240 gpg_error_t keydb_get_keyblock (KEYDB_HANDLE hd, KBNODE *ret_kb);
 241
 242 /* Replace the currently selected keyblock (i.e., the last result
 243    returned by keydb_search) with the key block in KB.
 244
 245    This doesn't do anything if --dry-run was specified.
 246
 247    Returns 0 on success.  Otherwise, it returns an error code.  */
 248 gpg_error_t keydb_update_keyblock (KEYDB_HANDLE hd, kbnode_t kb);
 249
 250 /* Insert a keyblock into one of the underlying keyrings or keyboxes.
 251
 252    Be default, the keyring / keybox from which the last search result
 253    came is used.  If there was no previous search result (or
 254    keydb_search_reset was called), then the keyring / keybox where the
 255    next search would start is used (i.e., the current file position).
 256
 257    Note: this doesn't do anything if --dry-run was specified.
 258
 259    Returns 0 on success.  Otherwise, it returns an error code.  */
 260 gpg_error_t keydb_insert_keyblock (KEYDB_HANDLE hd, kbnode_t kb);
 261
 262 /* Delete the currently selected keyblock.  If you haven't done a
 263    search yet on this database handle (or called keydb_search_reset),
 264    then this will return an error.
 265
 266    Returns 0 on success or an error code, if an error occurs.  */
 267 gpg_error_t keydb_delete_keyblock (KEYDB_HANDLE hd);
 268
 269 /* A database may consists of multiple keyrings / key boxes.  This
 270    sets the "file position" to the start of the first keyring / key
 271    box that is writable (i.e., doesn't have the read-only flag set).
 272
 273    This first tries the primary keyring (the last keyring (not
 274    keybox!) added using keydb_add_resource() and with
 275    KEYDB_RESOURCE_FLAG_PRIMARY set).  If that is not writable, then it
 276    tries the keyrings / keyboxes in the order in which they were
 277    added.  */
 278 gpg_error_t keydb_locate_writable (KEYDB_HANDLE hd);
 279
 280 /* Rebuild the on-disk caches of all key resources.  */
 281 void keydb_rebuild_caches (int noisy);
 282
 283 /* Return the number of skipped blocks (because they were to large to
 284    read from a keybox) since the last search reset.  */
 285 unsigned long keydb_get_skipped_counter (KEYDB_HANDLE hd);
 286
 287 /* Clears the current search result and resets the handle's position
 288    so that the next search starts at the beginning of the database
 289    (the start of the first resource).
 290
 291    Returns 0 on success and an error code if an error occured.
 292    (Currently, this function always returns 0 if HD is valid.)  */
 293 gpg_error_t keydb_search_reset (KEYDB_HANDLE hd);
 294
 295 /* Search the database for keys matching the search description.
 296
 297    DESC is an array of search terms with NDESC entries.  The search
 298    terms are or'd together.  That is, the next entry in the DB that
 299    matches any of the descriptions will be returned.
 300
 301    Note: this function resumes searching where the last search left
 302    off (i.e., at the current file position).  If you want to search
 303    from the start of the database, then you need to first call
 304    keydb_search_reset().
 305
 306    If no key matches the search description, returns
 307    GPG_ERR_NOT_FOUND.  If there was a match, returns 0.  If an error
 308    occured, returns an error code.
 309
 310    The returned key is considered to be selected and the raw data can,
 311    for instance, be returned by calling keydb_get_keyblock().  */
 312 gpg_error_t keydb_search (KEYDB_HANDLE hd, KEYDB_SEARCH_DESC *desc,
 313                           size_t ndesc, size_t *descindex);
 314
 315 /* Return the first non-legacy key in the database.
 316
 317    If you want the very first key in the database, you can directly
 318    call keydb_search with the search description
 319    KEYDB_SEARCH_MODE_FIRST.  */
 320 gpg_error_t keydb_search_first (KEYDB_HANDLE hd);
 321
 322 /* Return the next key (not the next matching key!).
 323
 324    Unlike calling keydb_search with KEYDB_SEARCH_MODE_NEXT, this
 325    function silently skips legacy keys.  */
 326 gpg_error_t keydb_search_next (KEYDB_HANDLE hd);
 327
 328 /* This is a convenience function for searching for keys with a long
 329    key id.
 330
 331    Note: this function resumes searching where the last search left
 332    off.  If you want to search the whole database, then you need to
 333    first call keydb_search_reset().  */
 334 gpg_error_t keydb_search_kid (KEYDB_HANDLE hd, u32 *kid);
 335
 336 /* This is a convenience function for searching for keys with a long
 337    (20 byte) fingerprint.  This function ignores legacy keys.
 338
 339    Note: this function resumes searching where the last search left
 340    off.  If you want to search the whole database, then you need to
 341    first call keydb_search_reset().  */
 342 gpg_error_t keydb_search_fpr (KEYDB_HANDLE hd, const byte *fpr);
 343
 344
 345 /*-- pkclist.c --*/
 346 void show_revocation_reason( PKT_public_key *pk, int mode );
 347 int  check_signatures_trust( PKT_signature *sig );
 348
 349 void release_pk_list (PK_LIST pk_list);
 350 int  build_pk_list (ctrl_t ctrl,
 351                     strlist_t rcpts, PK_LIST *ret_pk_list, unsigned use);
 352 gpg_error_t find_and_check_key (ctrl_t ctrl,
 353                                 const char *name, unsigned int use,
 354                                 int mark_hidden, pk_list_t *pk_list_addr);
 355
 356 int  algo_available( preftype_t preftype, int algo,
 357                      const union pref_hint *hint );
 358 int  select_algo_from_prefs( PK_LIST pk_list, int preftype,
 359                              int request, const union pref_hint *hint);
 360 int  select_mdc_from_pklist (PK_LIST pk_list);
 361 void warn_missing_mdc_from_pklist (PK_LIST pk_list);
 362 void warn_missing_aes_from_pklist (PK_LIST pk_list);
 363
 364 /*-- skclist.c --*/
 365 int  random_is_faked (void);
 366 void release_sk_list( SK_LIST sk_list );
 367 gpg_error_t  build_sk_list (strlist_t locusr, SK_LIST *ret_sk_list,
 368                             unsigned use);
 369
 370 /*-- passphrase.h --*/
 371 unsigned char encode_s2k_iterations (int iterations);
 372 assuan_context_t agent_open (int try, const char *orig_codeset);
 373 void agent_close (assuan_context_t ctx);
 374 int  have_static_passphrase(void);
 375 const char *get_static_passphrase (void);
 376 void set_passphrase_from_string(const char *pass);
 377 void read_passphrase_from_fd( int fd );
 378 void passphrase_clear_cache ( u32 *keyid, const char *cacheid, int algo );
 379 DEK *passphrase_to_dek_ext(u32 *keyid, int pubkey_algo,
 380                            int cipher_algo, STRING2KEY *s2k, int mode,
 381                            const char *tryagain_text,
 382                            const char *custdesc, const char *custprompt,
 383                            int *canceled);
 384 DEK *passphrase_to_dek( u32 *keyid, int pubkey_algo,
 385                         int cipher_algo, STRING2KEY *s2k, int mode,
 386                         const char *tryagain_text, int *canceled);
 387 void set_next_passphrase( const char *s );
 388 char *get_last_passphrase(void);
 389 void next_to_last_passphrase(void);
 390
 391 void emit_status_need_passphrase (u32 *keyid, u32 *mainkeyid, int pubkey_algo);
 392
 393 #define FORMAT_KEYDESC_NORMAL  0
 394 #define FORMAT_KEYDESC_IMPORT  1
 395 #define FORMAT_KEYDESC_EXPORT  2
 396 #define FORMAT_KEYDESC_DELKEY  3
 397 char *gpg_format_keydesc (PKT_public_key *pk, int mode, int escaped);
 398
 399
 400 /*-- getkey.c --*/
 401
 402 /* Cache a copy of a public key in the public key cache.  PK is not
 403    cached if caching is disabled (via getkey_disable_caches), if
 404    PK->FLAGS.DONT_CACHE is set, we don't know how to derive a key id
 405    from the public key (e.g., unsupported algorithm), or a key with
 406    the key id is already in the cache.
 407
 408    The public key packet is copied into the cache using
 409    copy_public_key.  Thus, any secret parts are not copied, for
 410    instance.
 411
 412    This cache is filled by get_pubkey and is read by get_pubkey and
 413    get_pubkey_fast.  */
 414 void cache_public_key( PKT_public_key *pk );
 415
 416 /* Disable and drop the public key cache (which is filled by
 417    cache_public_key and get_pubkey).  Note: there is currently no way
 418    to reenable this cache.  */
 419 void getkey_disable_caches(void);
 420
 421 /* Return the public key with the key id KEYID and store it in *PK.
 422    The resources in *PK should be released using
 423    release_public_key_parts().  This function also stores a copy of
 424    the public key in the user id cache (see cache_public_key).
 425
 426    If PK is NULL, this function just stores the public key in the
 427    cache and returns the usual return code.
 428
 429    PK->REQ_USAGE (which is a mask of PUBKEY_USAGE_SIG,
 430    PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT) is passed through to the
 431    lookup function.  If this is non-zero, only keys with the specified
 432    usage will be returned.  As such, it is essential that
 433    PK->REQ_USAGE be correctly initialized!
 434
 435    Returns 0 on success, GPG_ERR_NO_PUBKEY if there is no public key
 436    with the specified key id, or another error code if an error
 437    occurs.
 438
 439    If the data was not read from the cache, then the self-signed data
 440    has definately been merged into the public key using
 441    merge_selfsigs.  */
 442 int get_pubkey( PKT_public_key *pk, u32 *keyid );
 443
 444 /* Similar to get_pubkey, but it does not take PK->REQ_USAGE into
 445    account nor does it merge in the self-signed data.  This function
 446    also only considers primary keys.  It is intended to be used as a
 447    quick check of the key to avoid recursion.  It should only be used
 448    in very certain cases.  Like get_pubkey and unlike any of the other
 449    lookup functions, this function also consults the user id cache
 450    (see cache_public_key).
 451
 452    Return the public key in *PK.  The resources in *PK should be
 453    released using release_public_key_parts().  */
 454 int get_pubkey_fast ( PKT_public_key *pk, u32 *keyid );
 455
 456 /* Return the key block for the key with key id KEYID or NULL, if an
 457    error occurs.  Use release_kbnode() to release the key block.
 458
 459    The self-signed data has already been merged into the public key
 460    using merge_selfsigs.  */
 461 KBNODE get_pubkeyblock( u32 *keyid );
 462
 463 /* Find a public key identified by the name NAME.
 464
 465    If name appears to be a valid valid RFC822 mailbox (i.e., email
 466    address) and auto key lookup is enabled (no_akl == 0), then the
 467    specified auto key lookup methods (--auto-key-lookup) are used to
 468    import the key into the local keyring.  Otherwise, just the local
 469    keyring is consulted.
 470
 471
 472    If RETCTX is not NULL, then the constructed context is returned in
 473    *RETCTX so that getpubkey_next can be used to get subsequent
 474    results.  In this case, getkey_end() must be used to free the
 475    search context.  If RETCTX is not NULL, then RET_KDBHD must be
 476    NULL.
 477
 478    If PK is not NULL, the public key of the first result is returned
 479    in *PK.  Note: PK->REQ_USAGE must be valid!!!  PK->REQ_USAGE is
 480    passed through to the lookup function and is a mask of
 481    PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.  If this
 482    is non-zero, only keys with the specified usage will be returned.
 483    Note: The self-signed data has already been merged into the public
 484    key using merge_selfsigs.  Free *PK by calling
 485    release_public_key_parts (or, if PK was allocated using xfree, you
 486    can use free_public_key, which calls release_public_key_parts(PK)
 487    and then xfree(PK)).
 488
 489    NAME is a string, which is turned into a search query using
 490    classify_user_id.
 491
 492    If RET_KEYBLOCK is not NULL, the keyblock is returned in
 493    *RET_KEYBLOCK.  This should be freed using release_kbnode().
 494
 495    If RET_KDBHD is not NULL, then the new database handle used to
 496    conduct the search is returned in *RET_KDBHD.  This can be used to
 497    get subsequent results using keydb_search_next or to modify the
 498    returned record.  Note: in this case, no advanced filtering is done
 499    for subsequent results (e.g., PK->REQ_USAGE is not respected).
 500    Unlike RETCTX, this is always returned.
 501
 502    If INCLUDE_UNUSABLE is set, then unusable keys (see the
 503    documentation for skip_unusable for an exact definition) are
 504    skipped unless they are looked up by key id or by fingerprint.
 505
 506    If NO_AKL is set, then the auto key locate functionality is
 507    disabled and only the local key ring is considered.  Note: the
 508    local key ring is consulted even if local is not in the
 509    --auto-key-locate option list!
 510
 511    This function returns 0 on success.  Otherwise, an error code is
 512    returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
 513    (if want_secret is set) is returned if the key is not found.  */
 514 int get_pubkey_byname (ctrl_t ctrl,
 515                        GETKEY_CTX *retctx, PKT_public_key *pk,
 516                        const char *name,
 517                        KBNODE *ret_keyblock, KEYDB_HANDLE *ret_kdbhd,
 518                        int include_unusable, int no_akl );
 519
 520 /* Return the public key with the key id KEYID and store it in *PK.
 521    The resources should be released using release_public_key_parts().
 522
 523    Unlike other lookup functions, PK may not be NULL.  PK->REQ_USAGE
 524    is passed through to the lookup function and is a mask of
 525    PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.  Thus, it
 526    must be valid!  If this is non-zero, only keys with the specified
 527    usage will be returned.
 528
 529    Returns 0 on success.  If a public key with the specified key id is
 530    not found or a secret key is not available for that public key, an
 531    error code is returned.  Note: this function ignores legacy keys.
 532    An error code is also return if an error occurs.
 533
 534    The self-signed data has already been merged into the public key
 535    using merge_selfsigs.  */
 536 gpg_error_t get_seckey (PKT_public_key *pk, u32 *keyid);
 537
 538 /* Lookup a key with the specified fingerprint.
 539
 540    If PK is not NULL, the public key of the first result is returned
 541    in *PK.  Note: this function does an exact search and thus the
 542    returned public key may be a subkey rather than the primary key.
 543    Note: The self-signed data has already been merged into the public
 544    key using merge_selfsigs.  Free *PK by calling
 545    release_public_key_parts (or, if PK was allocated using xfree, you
 546    can use free_public_key, which calls release_public_key_parts(PK)
 547    and then xfree(PK)).
 548
 549    If PK->REQ_USAGE is set, it is used to filter the search results.
 550    (Thus, if PK is not NULL, PK->REQ_USAGE must be valid!!!)  See the
 551    documentation for finish_lookup to understand exactly how this is
 552    used.
 553
 554    If R_KEYBLOCK is not NULL, then the first result's keyblock is
 555    returned in *R_KEYBLOCK.  This should be freed using
 556    release_kbnode().
 557
 558    FPRINT is a byte array whose contents is the fingerprint to use as
 559    the search term.  FPRINT_LEN specifies the length of the
 560    fingerprint (in bytes).  Currently, only 16 and 20-byte
 561    fingerprints are supported.  */
 562 int get_pubkey_byfprint (PKT_public_key *pk,  kbnode_t *r_keyblock,
 563                          const byte *fprint, size_t fprint_len);
 564
 565 /* This function is similar to get_pubkey_byfprint, but it doesn't
 566    merge the self-signed data into the public key and subkeys or into
 567    the user ids.  It also doesn't add the key to the user id cache.
 568    Further, this function ignores PK->REQ_USAGE.
 569
 570    This function is intended to avoid recursion and, as such, should
 571    only be used in very specific situations.
 572
 573    Like get_pubkey_byfprint, PK may be NULL.  In that case, this
 574    function effectively just checks for the existence of the key.  */
 575 int get_pubkey_byfprint_fast (PKT_public_key *pk,
 576                               const byte *fprint, size_t fprint_len);
 577
 578 /* Return whether a secret key is available for the public key with
 579    key id KEYID.  This function ignores legacy keys.  Note: this is
 580    just a fast check and does not tell us whether the secret key is
 581    valid; this check merely indicates whether there is some secret key
 582    with the specified key id.  */
 583 int have_secret_key_with_kid (u32 *keyid);
 584
 585 /* Look up a secret key.
 586
 587    If PK is not NULL, the public key of the first result is returned
 588    in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
 589    set, it is used to filter the search results.  See the
 590    documentation for finish_lookup to understand exactly how this is
 591    used.  Note: The self-signed data has already been merged into the
 592    public key using merge_selfsigs.  Free *PK by calling
 593    release_public_key_parts (or, if PK was allocated using xfree, you
 594    can use free_public_key, which calls release_public_key_parts(PK)
 595    and then xfree(PK)).
 596
 597    If --default-key was set, then the specified key is looked up.  (In
 598    this case, the default key is returned even if it is considered
 599    unusable.  See the documentation for skip_unusable for exactly what
 600    this means.)
 601
 602    Otherwise, this initiates a DB scan that returns all keys that are
 603    usable (see previous paragraph for exactly what usable means) and
 604    for which a secret key is available.
 605
 606    This function returns the first match.  Additional results can be
 607    returned using getkey_next.  */
 608 gpg_error_t get_seckey_default (PKT_public_key *pk);
 609
 610 /* Search for keys matching some criteria.
 611
 612    If RETCTX is not NULL, then the constructed context is returned in
 613    *RETCTX so that getpubkey_next can be used to get subsequent
 614    results.  In this case, getkey_end() must be used to free the
 615    search context.  If RETCTX is not NULL, then RET_KDBHD must be
 616    NULL.
 617
 618    If PK is not NULL, the public key of the first result is returned
 619    in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
 620    set, it is used to filter the search results.  See the
 621    documentation for finish_lookup to understand exactly how this is
 622    used.  Note: The self-signed data has already been merged into the
 623    public key using merge_selfsigs.  Free *PK by calling
 624    release_public_key_parts (or, if PK was allocated using xfree, you
 625    can use free_public_key, which calls release_public_key_parts(PK)
 626    and then xfree(PK)).
 627
 628    If NAMES is not NULL, then a search query is constructed using
 629    classify_user_id on each of the strings in the list.  (Recall: the
 630    database does an OR of the terms, not an AND.)  If NAMES is
 631    NULL, then all results are returned.
 632
 633    If WANT_SECRET is set, then only keys with an available secret key
 634    (either locally or via key registered on a smartcard) are returned.
 635
 636    This function does not skip unusable keys (see the documentation
 637    for skip_unusable for an exact definition).
 638
 639    If RET_KEYBLOCK is not NULL, the keyblock is returned in
 640    *RET_KEYBLOCK.  This should be freed using release_kbnode().
 641
 642    This function returns 0 on success.  Otherwise, an error code is
 643    returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
 644    (if want_secret is set) is returned if the key is not found.  */
 645 gpg_error_t getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
 646                             strlist_t names, int want_secret,
 647                             kbnode_t *ret_keyblock);
 648
 649 /* Search for keys matching some criteria.
 650
 651    If RETCTX is not NULL, then the constructed context is returned in
 652    *RETCTX so that getpubkey_next can be used to get subsequent
 653    results.  In this case, getkey_end() must be used to free the
 654    search context.  If RETCTX is not NULL, then RET_KDBHD must be
 655    NULL.
 656
 657    If PK is not NULL, the public key of the first result is returned
 658    in *PK.  Note: PK->REQ_USAGE must be valid!!!  If PK->REQ_USAGE is
 659    set, it is used to filter the search results.  See the
 660    documentation for finish_lookup to understand exactly how this is
 661    used.  Note: The self-signed data has already been merged into the
 662    public key using merge_selfsigs.  Free *PK by calling
 663    release_public_key_parts (or, if PK was allocated using xfree, you
 664    can use free_public_key, which calls release_public_key_parts(PK)
 665    and then xfree(PK)).
 666
 667    If NAME is not NULL, then a search query is constructed using
 668    classify_user_id on the string.  In this case, even unusable keys
 669    (see the documentation for skip_unusable for an exact definition of
 670    unusable) are returned.  Otherwise, if --default-key was set, then
 671    that key is returned (even if it is unusable).  If neither of these
 672    conditions holds, then the first usable key is returned.
 673
 674    If WANT_SECRET is set, then only keys with an available secret key
 675    (either locally or via key registered on a smartcard) are returned.
 676
 677    This function does not skip unusable keys (see the documentation
 678    for skip_unusable for an exact definition).
 679
 680    If RET_KEYBLOCK is not NULL, the keyblock is returned in
 681    *RET_KEYBLOCK.  This should be freed using release_kbnode().
 682
 683    This function returns 0 on success.  Otherwise, an error code is
 684    returned.  In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
 685    (if want_secret is set) is returned if the key is not found.
 686
 687    FIXME: We also have the get_pubkey_byname function which has a
 688    different semantic.  Should be merged with this one.  */
 689 gpg_error_t getkey_byname (getkey_ctx_t *retctx, PKT_public_key *pk,
 690                            const char *name, int want_secret,
 691                            kbnode_t *ret_keyblock);
 692
 693 /* Return the next search result.
 694
 695    If PK is not NULL, the public key of the next result is returned in
 696    *PK.  Note: The self-signed data has already been merged into the
 697    public key using merge_selfsigs.  Free *PK by calling
 698    release_public_key_parts (or, if PK was allocated using xfree, you
 699    can use free_public_key, which calls release_public_key_parts(PK)
 700    and then xfree(PK)).
 701
 702    The self-signed data has already been merged into the public key
 703    using merge_selfsigs.  */
 704 gpg_error_t getkey_next (getkey_ctx_t ctx, PKT_public_key *pk,
 705                          kbnode_t *ret_keyblock);
 706
 707 /* Release any resources used by a key listing content.  This must be
 708    called on the context returned by, e.g., getkey_byname.  */
 709 void getkey_end (getkey_ctx_t ctx);
 710
 711 /* Return the database handle used by this context.  The context still
 712    owns the handle.  */
 713 KEYDB_HANDLE get_ctx_handle(GETKEY_CTX ctx);
 714
 715 /* Enumerate some secret keys (specifically, those specified with
 716    --default-key and --try-secret-key).  Use the following procedure:
 717
 718     1) Initialize a void pointer to NULL
 719     2) Pass a reference to this pointer to this function (content)
 720        and provide space for the secret key (sk)
 721     3) Call this function as long as it does not return an error (or
 722        until you are done).  The error code GPG_ERR_EOF indicates the
 723        end of the listing.
 724     4) Call this function a last time with SK set to NULL,
 725        so that can free it's context.
 726
 727    In pseudo-code:
 728
 729      void *ctx = NULL;
 730      PKT_public_key *sk = xmalloc_clear (sizeof (*sk));
 731      gpg_error_t err;
 732
 733      while ((err = enum_secret_keys (&ctx, sk)))
 734        {
 735          // Process SK.
 736
 737          if (done)
 738            break;
 739
 740          free_public_key (sk);
 741          sk = xmalloc_clear (sizeof (*sk));
 742        }
 743
 744      // Release any resources used by CTX.
 745      enum_secret_keys (&ctx, NULL);
 746      free_public_key (sk);
 747
 748      if (gpg_err_code (err) != GPG_ERR_EOF)
 749        ; // An error occured.
 750  */
 751 gpg_error_t enum_secret_keys (void **context, PKT_public_key *pk);
 752
 753 /* Set the mainkey_id fields for all keys in KEYBLOCK.  This is
 754    usually done by merge_selfsigs but at some places we only need the
 755    main_kid not a full merge.  The function also guarantees that all
 756    pk->keyids are computed. */
 757 void setup_main_keyids (kbnode_t keyblock);
 758
 759 /* KEYBLOCK corresponds to a public key block.  This function merges
 760    much of the information from the self-signed data into the public
 761    key, public subkey and user id data structures.  If you use the
 762    high-level search API (e.g., get_pubkey) for looking up key blocks,
 763    then you don't need to call this function.  This function is
 764    useful, however, if you change the keyblock, e.g., by adding or
 765    removing a self-signed data packet.  */
 766 void merge_keys_and_selfsig( KBNODE keyblock );
 767
 768 char*get_user_id_string_native( u32 *keyid );
 769 char*get_long_user_id_string( u32 *keyid );
 770 char*get_user_id( u32 *keyid, size_t *rn );
 771 char*get_user_id_native( u32 *keyid );
 772 char *get_user_id_byfpr (const byte *fpr, size_t *rn);
 773 char *get_user_id_byfpr_native (const byte *fpr);
 774
 775 void release_akl(void);
 776 int parse_auto_key_locate(char *options);
 777
 778 /*-- keyid.c --*/
 779 int pubkey_letter( int algo );
 780 char *pubkey_string (PKT_public_key *pk, char *buffer, size_t bufsize);
 781 #define PUBKEY_STRING_SIZE 32
 782 u32 v3_keyid (gcry_mpi_t a, u32 *ki);
 783 void hash_public_key( gcry_md_hd_t md, PKT_public_key *pk );
 784 size_t keystrlen(void);
 785 const char *keystr(u32 *keyid);
 786 const char *keystr_with_sub (u32 *main_kid, u32 *sub_kid);
 787 const char *keystr_from_pk(PKT_public_key *pk);
 788 const char *keystr_from_pk_with_sub (PKT_public_key *main_pk,
 789                                      PKT_public_key *sub_pk);
 790 const char *keystr_from_desc(KEYDB_SEARCH_DESC *desc);
 791 u32 keyid_from_pk( PKT_public_key *pk, u32 *keyid );
 792 u32 keyid_from_sig( PKT_signature *sig, u32 *keyid );
 793 u32 keyid_from_fingerprint(const byte *fprint, size_t fprint_len, u32 *keyid);
 794 byte *namehash_from_uid(PKT_user_id *uid);
 795 unsigned nbits_from_pk( PKT_public_key *pk );
 796 const char *datestr_from_pk( PKT_public_key *pk );
 797 const char *datestr_from_sig( PKT_signature *sig );
 798 const char *expirestr_from_pk( PKT_public_key *pk );
 799 const char *expirestr_from_sig( PKT_signature *sig );
 800 const char *revokestr_from_pk( PKT_public_key *pk );
 801 const char *usagestr_from_pk (PKT_public_key *pk, int fill);
 802 const char *colon_strtime (u32 t);
 803 const char *colon_datestr_from_pk (PKT_public_key *pk);
 804 const char *colon_datestr_from_sig (PKT_signature *sig);
 805 const char *colon_expirestr_from_sig (PKT_signature *sig);
 806 byte *fingerprint_from_pk( PKT_public_key *pk, byte *buf, size_t *ret_len );
 807 char *hexfingerprint (PKT_public_key *pk);
 808 gpg_error_t keygrip_from_pk (PKT_public_key *pk, unsigned char *array);
 809 gpg_error_t hexkeygrip_from_pk (PKT_public_key *pk, char **r_grip);
 810
 811
 812 /*-- kbnode.c --*/
 813 KBNODE new_kbnode( PACKET *pkt );
 814 KBNODE clone_kbnode( KBNODE node );
 815 void release_kbnode( KBNODE n );
 816 void delete_kbnode( KBNODE node );
 817 void add_kbnode( KBNODE root, KBNODE node );
 818 void insert_kbnode( KBNODE root, KBNODE node, int pkttype );
 819 void move_kbnode( KBNODE *root, KBNODE node, KBNODE where );
 820 void remove_kbnode( KBNODE *root, KBNODE node );
 821 KBNODE find_prev_kbnode( KBNODE root, KBNODE node, int pkttype );
 822 KBNODE find_next_kbnode( KBNODE node, int pkttype );
 823 KBNODE find_kbnode( KBNODE node, int pkttype );
 824 KBNODE walk_kbnode( KBNODE root, KBNODE *context, int all );
 825 void clear_kbnode_flags( KBNODE n );
 826 int  commit_kbnode( KBNODE *root );
 827 void dump_kbnode( KBNODE node );
 828
 829 #endif /*G10_KEYDB_H*/