Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

x509path.h
Go to the documentation of this file.
1 /*
2 * X.509 Cert Path Validation
3 * (C) 2010-2011 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7
8 #ifndef BOTAN_X509_CERT_PATH_VALIDATION_H__
9 #define BOTAN_X509_CERT_PATH_VALIDATION_H__
10
11 #include <botan/cert_status.h>
12 #include <botan/x509cert.h>
13 #include <botan/certstor.h>
14 #include <botan/ocsp.h>
15 #include <functional>
16 #include <set>
17 #include <chrono>
18
19 #if defined(BOTAN_TARGET_OS_HAS_THREADS) && defined(BOTAN_HAS_HTTP_UTIL)
20 #define BOTAN_HAS_ONLINE_REVOCATION_CHECKS
21 #endif
22
23 namespace Botan {
24
25 /**
26 * This type represents the validation status of an entire certificate path.
27 * There is one set of status codes for each certificate in the path.
28 */
29 typedef std::vector<std::set<Certificate_Status_Code>> CertificatePathStatusCodes;
30
31 /**
32 * Specifies restrictions on the PKIX path validation
33 */
34 class BOTAN_DLL Path_Validation_Restrictions
35 {
36 public:
37 /**
38 * @param require_rev if true, revocation information is required
39
40 * @param minimum_key_strength is the minimum strength (in terms of
41 * operations, eg 80 means 2^80) of a signature. Signatures weaker than
42 * this are rejected. If more than 80, SHA-1 signatures are also
43 * rejected. If possible use at least setting 110.
44 *
45 * 80 bit strength requires 1024 bit RSA
46 * 110 bit strength requires 2k bit RSA
47 * 128 bit strength requires ~3k bit RSA or P-256
48 * @param ocsp_all_intermediates Make OCSP requests for all CAs as
49 * well as end entity (if OCSP enabled in path validation request)
50 */
51 Path_Validation_Restrictions(bool require_rev = false,
52 size_t minimum_key_strength = 110,
53 bool ocsp_all_intermediates = false);
54
55 /**
56 * @param require_rev if true, revocation information is required
57 * @param minimum_key_strength is the minimum strength (in terms of
58 * operations, eg 80 means 2^80) of a signature. Signatures
59 * weaker than this are rejected.
60 * @param ocsp_all_intermediates Make OCSP requests for all CAs as
61 * well as end entity (if OCSP enabled in path validation request)
62 * @param trusted_hashes a set of trusted hashes. Any signatures
63 * created using a hash other than one of these will be
64 * rejected.
65 */
66 Path_Validation_Restrictions(bool require_rev,
67 size_t minimum_key_strength,
68 bool ocsp_all_intermediates,
69 const std::set<std::string>& trusted_hashes) :
70 m_require_revocation_information(require_rev),
71 m_ocsp_all_intermediates(ocsp_all_intermediates),
72 m_trusted_hashes(trusted_hashes),
73 m_minimum_key_strength(minimum_key_strength) {}
74
75 /**
76 * @return whether revocation information is required
77 */
78 bool require_revocation_information() const
79 { return m_require_revocation_information; }
80
81 /**
82 * @return whether all intermediate CAs should also be OCSPed. If false
83 * then only end entity OCSP is required/requested.
84 */
85 bool ocsp_all_intermediates() const
86 { return m_ocsp_all_intermediates; }
87
88 /**
89 * @return trusted signature hash functions
90 */
91 const std::set<std::string>& trusted_hashes() const
92 { return m_trusted_hashes; }
93
94 /**
95 * @return minimum required key strength
96 */
97 size_t minimum_key_strength() const
98 { return m_minimum_key_strength; }
99
100 private:
101 bool m_require_revocation_information;
102 bool m_ocsp_all_intermediates;
103 std::set<std::string> m_trusted_hashes;
104 size_t m_minimum_key_strength;
105 };
106
107 /**
108 * Represents the result of a PKIX path validation
109 */
110 class BOTAN_DLL Path_Validation_Result
111 {
112 public:
113 typedef Certificate_Status_Code Code;
114
115 /**
116 * @return the set of hash functions you are implicitly
117 * trusting by trusting this result.
118 */
119 std::set<std::string> trusted_hashes() const;
120
121 /**
122 * @return the trust root of the validation if successful
123 * throws an exception if the validation failed
124 */
125 const X509_Certificate& trust_root() const;
126
127 /**
128 * @return the full path from subject to trust root
129 * This path may be empty
130 */
131 const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path() const { return m_cert_path; }
132
133 /**
134 * @return true iff the validation was successful
135 */
136 bool successful_validation() const;
137
138 /**
139 * @return overall validation result code
140 */
141 Certificate_Status_Code result() const { return m_overall; }
142
143 /**
144 * @return a set of status codes for each certificate in the chain
145 */
146 const CertificatePathStatusCodes& all_statuses() const
147 { return m_all_status; }
148
149 /**
150 * @return string representation of the validation result
151 */
152 std::string result_string() const;
153
154 /**
155 * @param code validation status code
156 * @return corresponding validation status message
157 */
158 static const char* status_string(Certificate_Status_Code code);
159
160 /**
161 * Create a Path_Validation_Result
162 * @param status list of validation status codes
163 * @param cert_chain the certificate chain that was validated
164 */
165 Path_Validation_Result(CertificatePathStatusCodes status,
166 std::vector<std::shared_ptr<const X509_Certificate>>&& cert_chain);
167
168 /**
169 * Create a Path_Validation_Result
170 * @param status validation status code
171 */
172 explicit Path_Validation_Result(Certificate_Status_Code status) : m_overall(status) {}
173
174 private:
175 CertificatePathStatusCodes m_all_status;
176 std::vector<std::shared_ptr<const X509_Certificate>> m_cert_path;
177 Certificate_Status_Code m_overall;
178 };
179
180 /**
181 * PKIX Path Validation
182 * @param end_certs certificate chain to validate
183 * @param restrictions path validation restrictions
184 * @param trusted_roots list of certificate stores that contain trusted certificates
185 * @param hostname if not empty, compared against the DNS name in end_certs[0]
186 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
187 * @param validation_time what reference time to use for validation
188 * @param ocsp_timeout timeout for OCSP operations, 0 disables OCSP check
189 * @param ocsp_resp additional OCSP responses to consider (eg from peer)
190 * @return result of the path validation
191 */
192 Path_Validation_Result BOTAN_DLL x509_path_validate(
193 const std::vector<X509_Certificate>& end_certs,
194 const Path_Validation_Restrictions& restrictions,
195 const std::vector<Certificate_Store*>& trusted_roots,
196 const std::string& hostname = "",
197 Usage_Type usage = Usage_Type::UNSPECIFIED,
198 std::chrono::system_clock::time_point validation_time = std::chrono::system_clock::now(),
199 std::chrono::milliseconds ocsp_timeout = std::chrono::milliseconds(0),
200 const std::vector<std::shared_ptr<const OCSP::Response>>& ocsp_resp = {});
201
202 /**
203 * PKIX Path Validation
204 * @param end_cert certificate to validate
205 * @param restrictions path validation restrictions
206 * @param trusted_roots list of stores that contain trusted certificates
207 * @param hostname if not empty, compared against the DNS name in end_cert
208 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
209 * @param validation_time what reference time to use for validation
210 * @param ocsp_timeout timeoutput for OCSP operations, 0 disables OCSP check
211 * @param ocsp_resp additional OCSP responses to consider (eg from peer)
212 * @return result of the path validation
213 */
214 Path_Validation_Result BOTAN_DLL x509_path_validate(
215 const X509_Certificate& end_cert,
216 const Path_Validation_Restrictions& restrictions,
217 const std::vector<Certificate_Store*>& trusted_roots,
218 const std::string& hostname = "",
219 Usage_Type usage = Usage_Type::UNSPECIFIED,
220 std::chrono::system_clock::time_point validation_time = std::chrono::system_clock::now(),
221 std::chrono::milliseconds ocsp_timeout = std::chrono::milliseconds(0),
222 const std::vector<std::shared_ptr<const OCSP::Response>>& ocsp_resp = {});
223
224 /**
225 * PKIX Path Validation
226 * @param end_cert certificate to validate
227 * @param restrictions path validation restrictions
228 * @param store store that contains trusted certificates
229 * @param hostname if not empty, compared against the DNS name in end_cert
230 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
231 * @param validation_time what reference time to use for validation
232 * @param ocsp_timeout timeout for OCSP operations, 0 disables OCSP check
233 * @param ocsp_resp additional OCSP responses to consider (eg from peer)
234 * @return result of the path validation
235 */
236 Path_Validation_Result BOTAN_DLL x509_path_validate(
237 const X509_Certificate& end_cert,
238 const Path_Validation_Restrictions& restrictions,
239 const Certificate_Store& store,
240 const std::string& hostname = "",
241 Usage_Type usage = Usage_Type::UNSPECIFIED,
242 std::chrono::system_clock::time_point validation_time = std::chrono::system_clock::now(),
243 std::chrono::milliseconds ocsp_timeout = std::chrono::milliseconds(0),
244 const std::vector<std::shared_ptr<const OCSP::Response>>& ocsp_resp = {});
245
246 /**
247 * PKIX Path Validation
248 * @param end_certs certificate chain to validate
249 * @param restrictions path validation restrictions
250 * @param store store that contains trusted certificates
251 * @param hostname if not empty, compared against the DNS name in end_certs[0]
252 * @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
253 * @param validation_time what reference time to use for validation
254 * @param ocsp_timeout timeoutput for OCSP operations, 0 disables OCSP check
255 * @param ocsp_resp additional OCSP responses to consider (eg from peer)
256 * @return result of the path validation
257 */
258 Path_Validation_Result BOTAN_DLL x509_path_validate(
259 const std::vector<X509_Certificate>& end_certs,
260 const Path_Validation_Restrictions& restrictions,
261 const Certificate_Store& store,
262 const std::string& hostname = "",
263 Usage_Type usage = Usage_Type::UNSPECIFIED,
264 std::chrono::system_clock::time_point validation_time = std::chrono::system_clock::now(),
265 std::chrono::milliseconds ocsp_timeout = std::chrono::milliseconds(0),
266 const std::vector<std::shared_ptr<const OCSP::Response>>& ocsp_resp = {});
267
268
269 /**
270 * namespace PKIX holds the building blocks that are called by x509_path_validate.
271 * This allows custom validation logic to be written by applications and makes
272 * for easier testing, but unless you're positive you know what you're doing you
273 * probably want to just call x509_path_validate instead.
274 */
275 namespace PKIX {
276
277 /**
278 * Build certificate path
279 * @param cert_path_out output parameter, cert_path will be appended to this vector
280 * @param trusted_certstores list of certificate stores that contain trusted certificates
281 * @param end_entity the cert to be validated
282 * @param end_entity_extra optional list of additional untrusted certs for path building
283 * @return result of the path building operation (OK or error)
284 */
285 Certificate_Status_Code
286 BOTAN_DLL build_certificate_path(std::vector<std::shared_ptr<const X509_Certificate>>& cert_path_out,
287 const std::vector<Certificate_Store*>& trusted_certstores,
288 const std::shared_ptr<const X509_Certificate>& end_entity,
289 const std::vector<std::shared_ptr<const X509_Certificate>>& end_entity_extra);
290
291 /**
292 * Check the certificate chain, but not any revocation data
293 *
294 * @param cert_path path built by build_certificate_path with OK result
295 * @param ref_time whatever time you want to perform the validation
296 * against (normally current system clock)
297 * @param hostname the hostname
298 * @param usage end entity usage checks
299 * @param min_signature_algo_strength 80 or 110 typically
300 * Note 80 allows 1024 bit RSA and SHA-1. 110 allows 2048 bit RSA and SHA-2.
301 * Using 128 requires ECC (P-256) or ~3000 bit RSA keys.
302 * @param trusted_hashes set of trusted hash functions, empty means accept any
303 * hash we have an OID for
304 * @return vector of results on per certificate in the path, each containing a set of
305 * results. If all codes in the set are < Certificate_Status_Code::FIRST_ERROR_STATUS,
306 * then the result for that certificate is successful. If all results are
307 */
308 CertificatePathStatusCodes
309 BOTAN_DLL check_chain(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
310 std::chrono::system_clock::time_point ref_time,
311 const std::string& hostname,
312 Usage_Type usage,
313 size_t min_signature_algo_strength,
314 const std::set<std::string>& trusted_hashes);
315
316 /**
317 * Check OCSP responses for revocation information
318 * @param cert_path path already validated by check_chain
319 * @param ocsp_responses the OCSP responses to consider
320 * @param certstores trusted roots
321 * @param ref_time whatever time you want to perform the validation against
322 * (normally current system clock)
323 * @return revocation status
324 */
325 CertificatePathStatusCodes
326 BOTAN_DLL check_ocsp(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
327 const std::vector<std::shared_ptr<const OCSP::Response>>& ocsp_responses,
328 const std::vector<Certificate_Store*>& certstores,
329 std::chrono::system_clock::time_point ref_time);
330
331 /**
332 * Check CRLs for revocation infomration
333 * @param cert_path path already validated by check_chain
334 * @param crls the list of CRLs to check, it is assumed that crls[i] (if not null)
335 * is the associated CRL for the subject in cert_path[i].
336 * @param ref_time whatever time you want to perform the validation against
337 * (normally current system clock)
338 * @return revocation status
339 */
340 CertificatePathStatusCodes
341 BOTAN_DLL check_crl(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
342 const std::vector<std::shared_ptr<const X509_CRL>>& crls,
343 std::chrono::system_clock::time_point ref_time);
344
345 /**
346 * Check CRLs for revocation infomration
347 * @param cert_path path already validated by check_chain
348 * @param certstores a list of certificate stores to query for the CRL
349 * @param ref_time whatever time you want to perform the validation against
350 * (normally current system clock)
351 * @return revocation status
352 */
353 CertificatePathStatusCodes
354 BOTAN_DLL check_crl(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
355 const std::vector<Certificate_Store*>& certstores,
356 std::chrono::system_clock::time_point ref_time);
357
358 #if defined(BOTAN_HAS_ONLINE_REVOCATION_CHECKS)
359
360 /**
361 * Check OCSP using online (HTTP) access. Current version creates a thread and
362 * network connection per OCSP request made.
363 *
364 * @param cert_path path already validated by check_chain
365 * @param trusted_certstores a list of certstores with trusted certs
366 * @param ref_time whatever time you want to perform the validation against
367 * (normally current system clock)
368 * @param timeout for timing out the responses, though actually this function
369 * may block for up to timeout*cert_path.size()*C for some small C.
370 * @param ocsp_check_intermediate_CAs if true also performs OCSP on any intermediate
371 * CA certificates. If false, only does OCSP on the end entity cert.
372 * @return revocation status
373 */
374 CertificatePathStatusCodes
375 BOTAN_DLL check_ocsp_online(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
376 const std::vector<Certificate_Store*>& trusted_certstores,
377 std::chrono::system_clock::time_point ref_time,
378 std::chrono::milliseconds timeout,
379 bool ocsp_check_intermediate_CAs);
380
381 /**
382 * Check CRL using online (HTTP) access. Current version creates a thread and
383 * network connection per CRL access.
384
385 * @param cert_path path already validated by check_chain
386 * @param trusted_certstores a list of certstores with trusted certs
387 * @param certstore_to_recv_crls optional (nullptr to disable), all CRLs
388 * retreived will be saved to this cert store.
389 * @param ref_time whatever time you want to perform the validation against
390 * (normally current system clock)
391 * @param timeout for timing out the responses, though actually this function
392 * may block for up to timeout*cert_path.size()*C for some small C.
393 * @return revocation status
394 */
395 CertificatePathStatusCodes
396 BOTAN_DLL check_crl_online(const std::vector<std::shared_ptr<const X509_Certificate>>& cert_path,
397 const std::vector<Certificate_Store*>& trusted_certstores,
398 Certificate_Store_In_Memory* certstore_to_recv_crls,
399 std::chrono::system_clock::time_point ref_time,
400 std::chrono::milliseconds timeout);
401
402 #endif
403
404 /**
405 * Find overall status (OK, error) of a validation
406 * @param cert_status result of merge_revocation_status or check_chain
407 */
408 Certificate_Status_Code BOTAN_DLL overall_status(const CertificatePathStatusCodes& cert_status);
409
410 /**
411 * Merge the results from CRL and/or OCSP checks into chain_status
412 * @param chain_status the certificate status
413 * @param crl_status results from check_crl
414 * @param ocsp_status results from check_ocsp
415 * @param require_rev_on_end_entity require valid CRL or OCSP on end-entity cert
416 * @param require_rev_on_intermediates require valid CRL or OCSP on all intermediate certificates
417 */
418 void BOTAN_DLL merge_revocation_status(CertificatePathStatusCodes& chain_status,
419 const CertificatePathStatusCodes& crl_status,
420 const CertificatePathStatusCodes& ocsp_status,
421 bool require_rev_on_end_entity,
422 bool require_rev_on_intermediates);
423
424 }
425
426 }
427
428 #endif
Botan::PKIX::check_chain
CertificatePathStatusCodes BOTAN_DLL check_chain(const std::vector< std::shared_ptr< const X509_Certificate >> &cert_path, std::chrono::system_clock::time_point ref_time, const std::string &hostname, Usage_Type usage, size_t min_signature_algo_strength, const std::set< std::string > &trusted_hashes)
Definition: x509path.cpp:29
Botan::Path_Validation_Restrictions
Definition: x509path.h:34
Botan::PKIX::check_ocsp
CertificatePathStatusCodes BOTAN_DLL check_ocsp(const std::vector< std::shared_ptr< const X509_Certificate >> &cert_path, const std::vector< std::shared_ptr< const OCSP::Response >> &ocsp_responses, const std::vector< Certificate_Store * > &certstores, std::chrono::system_clock::time_point ref_time)
Definition: x509path.cpp:122
Botan::PKIX::overall_status
Certificate_Status_Code BOTAN_DLL overall_status(const CertificatePathStatusCodes &cert_status)
Definition: x509path.cpp:539
Botan::Path_Validation_Result::cert_path
const std::vector< std::shared_ptr< const X509_Certificate > > & cert_path() const
Definition: x509path.h:131
Botan::PKIX::merge_revocation_status
void BOTAN_DLL merge_revocation_status(CertificatePathStatusCodes &chain_status, const CertificatePathStatusCodes &crl_status, const CertificatePathStatusCodes &ocsp_status, bool require_rev_on_end_entity, bool require_rev_on_intermediates)
Definition: x509path.cpp:490
Botan::Path_Validation_Result::Code
Certificate_Status_Code Code
Definition: x509path.h:113
Botan::Path_Validation_Restrictions::require_revocation_information
bool require_revocation_information() const
Definition: x509path.h:78
Botan::X509_Certificate
Definition: x509cert.h:36
Botan::Path_Validation_Result::result
Certificate_Status_Code result() const
Definition: x509path.h:141
Botan::PKIX::check_crl
CertificatePathStatusCodes BOTAN_DLL check_crl(const std::vector< std::shared_ptr< const X509_Certificate >> &cert_path, const std::vector< std::shared_ptr< const X509_CRL >> &crls, std::chrono::system_clock::time_point ref_time)
Definition: x509path.cpp:171
Botan::Path_Validation_Result
Definition: x509path.h:110
Botan
Definition: alg_id.cpp:13
Botan::Path_Validation_Restrictions::ocsp_all_intermediates
bool ocsp_all_intermediates() const
Definition: x509path.h:85
Botan::Path_Validation_Result::Path_Validation_Result
Path_Validation_Result(Certificate_Status_Code status)
Definition: x509path.h:172
Botan::Path_Validation_Result::all_statuses
const CertificatePathStatusCodes & all_statuses() const
Definition: x509path.h:146
Botan::x509_path_validate
Path_Validation_Result x509_path_validate(const std::vector< X509_Certificate > &end_certs, const Path_Validation_Restrictions &restrictions, const std::vector< Certificate_Store * > &trusted_roots, const std::string &hostname, Usage_Type usage, std::chrono::system_clock::time_point ref_time, std::chrono::milliseconds ocsp_timeout, const std::vector< std::shared_ptr< const OCSP::Response >> &ocsp_resp)
Definition: x509path.cpp:562
Botan::Path_Validation_Restrictions::Path_Validation_Restrictions
Path_Validation_Restrictions(bool require_rev, size_t minimum_key_strength, bool ocsp_all_intermediates, const std::set< std::string > &trusted_hashes)
Definition: x509path.h:66
Botan::Path_Validation_Restrictions::trusted_hashes
const std::set< std::string > & trusted_hashes() const
Definition: x509path.h:91
Botan::PKIX::build_certificate_path
Certificate_Status_Code BOTAN_DLL build_certificate_path(std::vector< std::shared_ptr< const X509_Certificate >> &cert_path_out, const std::vector< Certificate_Store * > &trusted_certstores, const std::shared_ptr< const X509_Certificate > &end_entity, const std::vector< std::shared_ptr< const X509_Certificate >> &end_entity_extra)
Definition: x509path.cpp:414
Botan::CertificatePathStatusCodes
std::vector< std::set< Certificate_Status_Code > > CertificatePathStatusCodes
Definition: x509path.h:29
Botan::Usage_Type::UNSPECIFIED
Botan::Certificate_Store_In_Memory
Definition: certstor.h:74
Botan::Certificate_Status_Code
Certificate_Status_Code
Definition: cert_status.h:18
Botan::Path_Validation_Restrictions::minimum_key_strength
size_t minimum_key_strength() const
Definition: x509path.h:97
Botan::Usage_Type
Usage_Type
Definition: x509cert.h:24