dirmngr: Reduce default LDAP timeout to 15 seconds.
[gnupg.git] / dirmngr / certcache.h
1 /* certcache.h - Certificate caching
2  *      Copyright (C) 2004, 2008 g10 Code GmbH
3  *
4  * This file is part of DirMngr.
5  *
6  * DirMngr is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * DirMngr is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
19  */
20
21 #ifndef CERTCACHE_H
22 #define CERTCACHE_H
23
24 /* The origin of the trusted root certificates.  */
25 enum {
26   CERTTRUST_CLASS_SYSTEM  = 1, /* From the system's list of trusted certs. */
27   CERTTRUST_CLASS_CONFIG  = 2, /* From dirmngr's config files.         */
28   CERTTRUST_CLASS_HKP     = 4, /* From --hkp-cacert                    */
29   CERTTRUST_CLASS_HKPSPOOL= 8, /* The one and only from sks-keyservers */
30 };
31
32
33 /* First time initialization of the certificate cache.  */
34 void cert_cache_init (strlist_t hkp_cacerts);
35
36 /* Deinitialize the certificate cache.  */
37 void cert_cache_deinit (int full);
38
39 /* Print some statistics to the log file.  */
40 void cert_cache_print_stats (void);
41
42 /* Return true if any cert of a class in MASK is permanently loaded.  */
43 int cert_cache_any_in_class (unsigned int mask);
44
45 /* Compute the fingerprint of the certificate CERT and put it into
46    the 20 bytes large buffer DIGEST.  Return address of this buffer.  */
47 unsigned char *cert_compute_fpr (ksba_cert_t cert, unsigned char *digest);
48
49 /* Put CERT into the certificate cache.  */
50 gpg_error_t cache_cert (ksba_cert_t cert);
51
52 /* Put CERT into the certificate cache and return the fingerprint. */
53 gpg_error_t cache_cert_silent (ksba_cert_t cert, void *fpr_buffer);
54
55 /* Return 0 if the certificate is a trusted certificate. Returns
56  * GPG_ERR_NOT_TRUSTED if it is not trusted or other error codes in
57  * case of systems errors.  TRUSTCLASSES are the bitwise ORed
58  * CERTTRUST_CLASS values to use for the check.  */
59 gpg_error_t is_trusted_cert (ksba_cert_t cert, unsigned trustclasses);
60
61 /* Return a certificate object for the given fingerprint.  FPR is
62    expected to be a 20 byte binary SHA-1 fingerprint.  If no matching
63    certificate is available in the cache NULL is returned.  The caller
64    must release a returned certificate.  */
65 ksba_cert_t get_cert_byfpr (const unsigned char *fpr);
66
67 /* Return a certificate object for the given fingerprint.  STRING is
68    expected to be a SHA-1 fingerprint in standard hex notation with or
69    without colons.  If no matching certificate is available in the
70    cache NULL is returned.  The caller must release a returned
71    certificate.  */
72 ksba_cert_t get_cert_byhexfpr (const char *string);
73
74 /* Return the certificate matching ISSUER_DN and SERIALNO.  */
75 ksba_cert_t get_cert_bysn (const char *issuer_dn, ksba_sexp_t serialno);
76
77 /* Return the certificate matching ISSUER_DN.  SEQ should initially be
78    set to 0 and bumped up to get the next issuer with that DN. */
79 ksba_cert_t get_cert_byissuer (const char *issuer_dn, unsigned int seq);
80
81 /* Return the certificate matching SUBJECT_DN.  SEQ should initially be
82    set to 0 and bumped up to get the next issuer with that DN. */
83 ksba_cert_t get_cert_bysubject (const char *subject_dn, unsigned int seq);
84
85 /* Given PATTERN, which is a string as used by GnuPG to specify a
86    certificate, return all matching certificates by calling the
87    supplied function RETFNC.  */
88 gpg_error_t get_certs_bypattern (const char *pattern,
89                                  gpg_error_t (*retfnc)(void*,ksba_cert_t),
90                                  void *retfnc_data);
91
92 /* Return the certificate matching ISSUER_DN and SERIALNO; if it is
93    not already in the cache, try to find it from other resources.  */
94 ksba_cert_t find_cert_bysn (ctrl_t ctrl,
95                             const char *issuer_dn, ksba_sexp_t serialno);
96
97
98 /* Return the certificate matching SUBJECT_DN and (if not NULL) KEYID. If
99    it is not already in the cache, try to find it from other
100    resources.  Note, that the external search does not work for user
101    certificates because the LDAP lookup is on the caCertificate
102    attribute. For our purposes this is just fine.  */
103 ksba_cert_t find_cert_bysubject (ctrl_t ctrl,
104                                  const char *subject_dn, ksba_sexp_t keyid);
105
106 /* Given the certificate CERT locate the issuer for this certificate
107    and return it at R_CERT.  Returns 0 on success or
108    GPG_ERR_NOT_FOUND.  */
109 gpg_error_t find_issuing_cert (ctrl_t ctrl,
110                                ksba_cert_t cert, ksba_cert_t *r_cert);
111
112
113
114 /* A simple list of certificates.  */
115 struct certlist_s
116 {
117   struct certlist_s *next;
118   ksba_cert_t cert;
119   unsigned char fpr[20];  /* of the certificate.  */
120 };
121 typedef struct certlist_s *certlist_t;
122
123 gpg_error_t read_certlist_from_stream (certlist_t *r_certlist, estream_t fp);
124 void release_certlist (certlist_t cl);
125
126
127
128 #endif /*CERTCACHE_H*/