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