g10: Remove unused prototype (get_pubkey_byfpr).
[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 /****************
73  * A data structre 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 void cache_public_key( PKT_public_key *pk );
402 void getkey_disable_caches(void);
403 int get_pubkey( PKT_public_key *pk, u32 *keyid );
404 int get_pubkey_fast ( PKT_public_key *pk, u32 *keyid );
405 KBNODE get_pubkeyblock( u32 *keyid );
406 int get_pubkey_byname (ctrl_t ctrl,
407                        GETKEY_CTX *rx, PKT_public_key *pk,  const char *name,
408                        KBNODE *ret_keyblock, KEYDB_HANDLE *ret_kdbhd,
409                        int include_unusable, int no_akl );
410 int get_pubkey_next( GETKEY_CTX ctx, PKT_public_key *pk, KBNODE *ret_keyblock );
411 void get_pubkey_end( GETKEY_CTX ctx );
412 gpg_error_t get_seckey (PKT_public_key *pk, u32 *keyid);
413 int get_pubkey_byfprint (PKT_public_key *pk,  kbnode_t *r_keyblock,
414                          const byte *fprint, size_t fprint_len);
415 int get_pubkey_byfprint_fast (PKT_public_key *pk,
416                               const byte *fprint, size_t fprint_len);
417 int get_keyblock_byfprint( KBNODE *ret_keyblock, const byte *fprint,
418                                                  size_t fprint_len );
419
420 /* Return whether a secret key is available for the public key with
421    key id KEYID.  Note: this is just a fast check and does not tell us
422    whether the secret key is valid; this check merely indicates
423    whether there is some secret key with the specified key id.  */
424 int have_secret_key_with_kid (u32 *keyid);
425
426 gpg_error_t get_seckey_byname (PKT_public_key *pk, const char *name);
427
428 gpg_error_t get_seckey_byfprint (PKT_public_key *pk,
429                                  const byte *fprint, size_t fprint_len);
430 gpg_error_t get_seckeyblock_byfprint (kbnode_t *ret_keyblock,
431                                       const byte *fprint, size_t fprint_len);
432
433 gpg_error_t getkey_bynames (getkey_ctx_t *retctx, PKT_public_key *pk,
434                             strlist_t names, int want_secret,
435                             kbnode_t *ret_keyblock);
436 gpg_error_t getkey_byname (getkey_ctx_t *retctx, PKT_public_key *pk,
437                            const char *name, int want_secret,
438                            kbnode_t *ret_keyblock);
439 gpg_error_t getkey_next (getkey_ctx_t ctx, PKT_public_key *pk,
440                          kbnode_t *ret_keyblock);
441 void getkey_end (getkey_ctx_t ctx);
442
443 gpg_error_t enum_secret_keys (void **context, PKT_public_key *pk);
444
445 void setup_main_keyids (kbnode_t keyblock);
446 void merge_keys_and_selfsig( KBNODE keyblock );
447 char*get_user_id_string_native( u32 *keyid );
448 char*get_long_user_id_string( u32 *keyid );
449 char*get_user_id( u32 *keyid, size_t *rn );
450 char*get_user_id_native( u32 *keyid );
451 char *get_user_id_byfpr (const byte *fpr, size_t *rn);
452 char *get_user_id_byfpr_native (const byte *fpr);
453 KEYDB_HANDLE get_ctx_handle(GETKEY_CTX ctx);
454 void release_akl(void);
455 int parse_auto_key_locate(char *options);
456
457 /*-- keyid.c --*/
458 int pubkey_letter( int algo );
459 char *pubkey_string (PKT_public_key *pk, char *buffer, size_t bufsize);
460 #define PUBKEY_STRING_SIZE 32
461 u32 v3_keyid (gcry_mpi_t a, u32 *ki);
462 void hash_public_key( gcry_md_hd_t md, PKT_public_key *pk );
463 size_t keystrlen(void);
464 const char *keystr(u32 *keyid);
465 const char *keystr_with_sub (u32 *main_kid, u32 *sub_kid);
466 const char *keystr_from_pk(PKT_public_key *pk);
467 const char *keystr_from_pk_with_sub (PKT_public_key *main_pk,
468                                      PKT_public_key *sub_pk);
469 const char *keystr_from_desc(KEYDB_SEARCH_DESC *desc);
470 u32 keyid_from_pk( PKT_public_key *pk, u32 *keyid );
471 u32 keyid_from_sig( PKT_signature *sig, u32 *keyid );
472 u32 keyid_from_fingerprint(const byte *fprint, size_t fprint_len, u32 *keyid);
473 byte *namehash_from_uid(PKT_user_id *uid);
474 unsigned nbits_from_pk( PKT_public_key *pk );
475 const char *datestr_from_pk( PKT_public_key *pk );
476 const char *datestr_from_sig( PKT_signature *sig );
477 const char *expirestr_from_pk( PKT_public_key *pk );
478 const char *expirestr_from_sig( PKT_signature *sig );
479 const char *revokestr_from_pk( PKT_public_key *pk );
480 const char *usagestr_from_pk (PKT_public_key *pk, int fill);
481 const char *colon_strtime (u32 t);
482 const char *colon_datestr_from_pk (PKT_public_key *pk);
483 const char *colon_datestr_from_sig (PKT_signature *sig);
484 const char *colon_expirestr_from_sig (PKT_signature *sig);
485 byte *fingerprint_from_pk( PKT_public_key *pk, byte *buf, size_t *ret_len );
486 char *hexfingerprint (PKT_public_key *pk);
487 gpg_error_t keygrip_from_pk (PKT_public_key *pk, unsigned char *array);
488 gpg_error_t hexkeygrip_from_pk (PKT_public_key *pk, char **r_grip);
489
490
491 /*-- kbnode.c --*/
492 KBNODE new_kbnode( PACKET *pkt );
493 KBNODE clone_kbnode( KBNODE node );
494 void release_kbnode( KBNODE n );
495 void delete_kbnode( KBNODE node );
496 void add_kbnode( KBNODE root, KBNODE node );
497 void insert_kbnode( KBNODE root, KBNODE node, int pkttype );
498 void move_kbnode( KBNODE *root, KBNODE node, KBNODE where );
499 void remove_kbnode( KBNODE *root, KBNODE node );
500 KBNODE find_prev_kbnode( KBNODE root, KBNODE node, int pkttype );
501 KBNODE find_next_kbnode( KBNODE node, int pkttype );
502 KBNODE find_kbnode( KBNODE node, int pkttype );
503 KBNODE walk_kbnode( KBNODE root, KBNODE *context, int all );
504 void clear_kbnode_flags( KBNODE n );
505 int  commit_kbnode( KBNODE *root );
506 void dump_kbnode( KBNODE node );
507
508 #endif /*G10_KEYDB_H*/