/src/botan/build/include/botan/x509cert.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * X.509 Certificates |
3 | | * (C) 1999-2007,2015,2017 Jack Lloyd |
4 | | * |
5 | | * Botan is released under the Simplified BSD License (see license.txt) |
6 | | */ |
7 | | |
8 | | #ifndef BOTAN_X509_CERTS_H_ |
9 | | #define BOTAN_X509_CERTS_H_ |
10 | | |
11 | | #include <botan/x509_obj.h> |
12 | | #include <memory> |
13 | | |
14 | | namespace Botan { |
15 | | |
16 | | class Public_Key; |
17 | | class X509_DN; |
18 | | class Extensions; |
19 | | class AlternativeName; |
20 | | class NameConstraints; |
21 | | |
22 | | enum class Usage_Type |
23 | | { |
24 | | UNSPECIFIED, // no restrictions |
25 | | TLS_SERVER_AUTH, |
26 | | TLS_CLIENT_AUTH, |
27 | | CERTIFICATE_AUTHORITY, |
28 | | OCSP_RESPONDER, |
29 | | ENCRYPTION |
30 | | }; |
31 | | |
32 | | struct X509_Certificate_Data; |
33 | | |
34 | | /** |
35 | | * This class represents an X.509 Certificate |
36 | | */ |
37 | | class BOTAN_PUBLIC_API(2,0) X509_Certificate : public X509_Object |
38 | | { |
39 | | public: |
40 | | /** |
41 | | * Return a newly allocated copy of the public key associated |
42 | | * with the subject of this certificate. This object is owned |
43 | | * by the caller. |
44 | | * |
45 | | * Prefer load_subject_public_key in new code |
46 | | * |
47 | | * @return public key |
48 | | */ |
49 | | Public_Key* subject_public_key() const; |
50 | | |
51 | | /** |
52 | | * Create a public key object associated with the public key bits in this |
53 | | * certificate. If the public key bits was valid for X.509 encoding |
54 | | * purposes but invalid algorithmically (for example, RSA with an even |
55 | | * modulus) that will be detected at this point, and an exception will be |
56 | | * thrown. |
57 | | * |
58 | | * @return subject public key of this certificate |
59 | | */ |
60 | | std::unique_ptr<Public_Key> load_subject_public_key() const; |
61 | | |
62 | | /** |
63 | | * Get the public key associated with this certificate. This includes the |
64 | | * outer AlgorithmIdentifier |
65 | | * @return subject public key of this certificate |
66 | | */ |
67 | | const std::vector<uint8_t>& subject_public_key_bits() const; |
68 | | |
69 | | /** |
70 | | * Get the SubjectPublicKeyInfo associated with this certificate. |
71 | | * @return subject public key info of this certificate |
72 | | */ |
73 | | const std::vector<uint8_t>& subject_public_key_info() const; |
74 | | |
75 | | /** |
76 | | * Return the algorithm identifier of the public key |
77 | | */ |
78 | | const AlgorithmIdentifier& subject_public_key_algo() const; |
79 | | |
80 | | /** |
81 | | * Get the bit string of the public key associated with this certificate |
82 | | * @return public key bits |
83 | | */ |
84 | | const std::vector<uint8_t>& subject_public_key_bitstring() const; |
85 | | |
86 | | /** |
87 | | * Get the SHA-1 bit string of the public key associated with this certificate. |
88 | | * This is used for OCSP among other protocols. |
89 | | * This function will throw if SHA-1 is not available. |
90 | | * @return hash of subject public key of this certificate |
91 | | */ |
92 | | const std::vector<uint8_t>& subject_public_key_bitstring_sha1() const; |
93 | | |
94 | | /** |
95 | | * Get the certificate's issuer distinguished name (DN). |
96 | | * @return issuer DN of this certificate |
97 | | */ |
98 | | const X509_DN& issuer_dn() const; |
99 | | |
100 | | /** |
101 | | * Get the certificate's subject distinguished name (DN). |
102 | | * @return subject DN of this certificate |
103 | | */ |
104 | | const X509_DN& subject_dn() const; |
105 | | |
106 | | /** |
107 | | * Get a value for a specific subject_info parameter name. |
108 | | * @param name the name of the parameter to look up. Possible names include |
109 | | * "X509.Certificate.version", "X509.Certificate.serial", |
110 | | * "X509.Certificate.start", "X509.Certificate.end", |
111 | | * "X509.Certificate.v2.key_id", "X509.Certificate.public_key", |
112 | | * "X509v3.BasicConstraints.path_constraint", |
113 | | * "X509v3.BasicConstraints.is_ca", "X509v3.NameConstraints", |
114 | | * "X509v3.ExtendedKeyUsage", "X509v3.CertificatePolicies", |
115 | | * "X509v3.SubjectKeyIdentifier", "X509.Certificate.serial", |
116 | | * "X520.CommonName", "X520.Organization", "X520.Country", |
117 | | * "RFC822" (Email in SAN) or "PKCS9.EmailAddress" (Email in DN). |
118 | | * @return value(s) of the specified parameter |
119 | | */ |
120 | | std::vector<std::string> subject_info(const std::string& name) const; |
121 | | |
122 | | /** |
123 | | * Get a value for a specific subject_info parameter name. |
124 | | * @param name the name of the parameter to look up. Possible names are |
125 | | * "X509.Certificate.v2.key_id" or "X509v3.AuthorityKeyIdentifier". |
126 | | * @return value(s) of the specified parameter |
127 | | */ |
128 | | std::vector<std::string> issuer_info(const std::string& name) const; |
129 | | |
130 | | /** |
131 | | * Raw issuer DN bits |
132 | | */ |
133 | | const std::vector<uint8_t>& raw_issuer_dn() const; |
134 | | |
135 | | /** |
136 | | * SHA-256 of Raw issuer DN |
137 | | */ |
138 | | std::vector<uint8_t> raw_issuer_dn_sha256() const; |
139 | | |
140 | | /** |
141 | | * Raw subject DN |
142 | | */ |
143 | | const std::vector<uint8_t>& raw_subject_dn() const; |
144 | | |
145 | | /** |
146 | | * SHA-256 of Raw subject DN |
147 | | */ |
148 | | std::vector<uint8_t> raw_subject_dn_sha256() const; |
149 | | |
150 | | /** |
151 | | * Get the notBefore of the certificate as X509_Time |
152 | | * @return notBefore of the certificate |
153 | | */ |
154 | | const X509_Time& not_before() const; |
155 | | |
156 | | /** |
157 | | * Get the notAfter of the certificate as X509_Time |
158 | | * @return notAfter of the certificate |
159 | | */ |
160 | | const X509_Time& not_after() const; |
161 | | |
162 | | /** |
163 | | * Get the X509 version of this certificate object. |
164 | | * @return X509 version |
165 | | */ |
166 | | uint32_t x509_version() const; |
167 | | |
168 | | /** |
169 | | * Get the serial number of this certificate. |
170 | | * @return certificates serial number |
171 | | */ |
172 | | const std::vector<uint8_t>& serial_number() const; |
173 | | |
174 | | /** |
175 | | * Get the serial number's sign |
176 | | * @return 1 iff the serial is negative. |
177 | | */ |
178 | | bool is_serial_negative() const; |
179 | | |
180 | | /** |
181 | | * Get the DER encoded AuthorityKeyIdentifier of this certificate. |
182 | | * @return DER encoded AuthorityKeyIdentifier |
183 | | */ |
184 | | const std::vector<uint8_t>& authority_key_id() const; |
185 | | |
186 | | /** |
187 | | * Get the DER encoded SubjectKeyIdentifier of this certificate. |
188 | | * @return DER encoded SubjectKeyIdentifier |
189 | | */ |
190 | | const std::vector<uint8_t>& subject_key_id() const; |
191 | | |
192 | | /** |
193 | | * Check whether this certificate is self signed. |
194 | | * If the DN issuer and subject agree, |
195 | | * @return true if this certificate is self signed |
196 | | */ |
197 | | bool is_self_signed() const; |
198 | | |
199 | | /** |
200 | | * Check whether this certificate is a CA certificate. |
201 | | * @return true if this certificate is a CA certificate |
202 | | */ |
203 | | bool is_CA_cert() const; |
204 | | |
205 | | /** |
206 | | * Returns true if the specified @param usage is set in the key usage extension |
207 | | * or if no key usage constraints are set at all. |
208 | | * To check if a certain key constraint is set in the certificate |
209 | | * use @see X509_Certificate#has_constraints. |
210 | | */ |
211 | | bool allowed_usage(Key_Constraints usage) const; |
212 | | |
213 | | /** |
214 | | * Returns true if the specified @param usage is set in the extended key usage extension |
215 | | * or if no extended key usage constraints are set at all. |
216 | | * To check if a certain extended key constraint is set in the certificate |
217 | | * use @see X509_Certificate#has_ex_constraint. |
218 | | */ |
219 | | bool allowed_extended_usage(const std::string& usage) const; |
220 | | |
221 | | /** |
222 | | * Returns true if the specified usage is set in the extended key usage extension, |
223 | | * or if no extended key usage constraints are set at all. |
224 | | * To check if a certain extended key constraint is set in the certificate |
225 | | * use @see X509_Certificate#has_ex_constraint. |
226 | | */ |
227 | | bool allowed_extended_usage(const OID& usage) const; |
228 | | |
229 | | /** |
230 | | * Returns true if the required key and extended key constraints are set in the certificate |
231 | | * for the specified @param usage or if no key constraints are set in both the key usage |
232 | | * and extended key usage extension. |
233 | | */ |
234 | | bool allowed_usage(Usage_Type usage) const; |
235 | | |
236 | | /** |
237 | | * Returns true if the specified @param constraints are included in the key |
238 | | * usage extension. |
239 | | */ |
240 | | bool has_constraints(Key_Constraints constraints) const; |
241 | | |
242 | | /** |
243 | | * Returns true if and only if OID @param ex_constraint is |
244 | | * included in the extended key extension. |
245 | | */ |
246 | | bool has_ex_constraint(const OID& ex_constraint) const; |
247 | | |
248 | | /** |
249 | | * Get the path limit as defined in the BasicConstraints extension of |
250 | | * this certificate. |
251 | | * @return path limit |
252 | | */ |
253 | | uint32_t path_limit() const; |
254 | | |
255 | | /** |
256 | | * Check whenever a given X509 Extension is marked critical in this |
257 | | * certificate. |
258 | | */ |
259 | | bool is_critical(const std::string& ex_name) const; |
260 | | |
261 | | /** |
262 | | * Get the key constraints as defined in the KeyUsage extension of this |
263 | | * certificate. |
264 | | * @return key constraints |
265 | | */ |
266 | | Key_Constraints constraints() const; |
267 | | |
268 | | /** |
269 | | * Get the key usage as defined in the ExtendedKeyUsage extension |
270 | | * of this certificate, or else an empty vector. |
271 | | * @return key usage |
272 | | */ |
273 | | const std::vector<OID>& extended_key_usage() const; |
274 | | |
275 | | /** |
276 | | * Get the name constraints as defined in the NameConstraints |
277 | | * extension of this certificate. |
278 | | * @return name constraints |
279 | | */ |
280 | | const NameConstraints& name_constraints() const; |
281 | | |
282 | | /** |
283 | | * Get the policies as defined in the CertificatePolicies extension |
284 | | * of this certificate. |
285 | | * @return certificate policies |
286 | | */ |
287 | | const std::vector<OID>& certificate_policy_oids() const; |
288 | | |
289 | | /** |
290 | | * Get all extensions of this certificate. |
291 | | * @return certificate extensions |
292 | | */ |
293 | | const Extensions& v3_extensions() const; |
294 | | |
295 | | /** |
296 | | * Return the v2 issuer key ID. v2 key IDs are almost never used, |
297 | | * instead see v3_subject_key_id. |
298 | | */ |
299 | | const std::vector<uint8_t>& v2_issuer_key_id() const; |
300 | | |
301 | | /** |
302 | | * Return the v2 subject key ID. v2 key IDs are almost never used, |
303 | | * instead see v3_subject_key_id. |
304 | | */ |
305 | | const std::vector<uint8_t>& v2_subject_key_id() const; |
306 | | |
307 | | /** |
308 | | * Return the subject alternative names (DNS, IP, ...) |
309 | | */ |
310 | | const AlternativeName& subject_alt_name() const; |
311 | | |
312 | | /** |
313 | | * Return the issuer alternative names (DNS, IP, ...) |
314 | | */ |
315 | | const AlternativeName& issuer_alt_name() const; |
316 | | |
317 | | /** |
318 | | * Return the listed address of an OCSP responder, or empty if not set |
319 | | */ |
320 | | std::string ocsp_responder() const; |
321 | | |
322 | | /** |
323 | | * Return the listed addresses of ca issuers, or empty if not set |
324 | | */ |
325 | | std::vector<std::string> ca_issuers() const; |
326 | | |
327 | | /** |
328 | | * Return the CRL distribution point, or empty if not set |
329 | | */ |
330 | | std::string crl_distribution_point() const; |
331 | | |
332 | | /** |
333 | | * @return a free-form string describing the certificate |
334 | | */ |
335 | | std::string to_string() const; |
336 | | |
337 | | /** |
338 | | * @return a fingerprint of the certificate |
339 | | * @param hash_name hash function used to calculate the fingerprint |
340 | | */ |
341 | | std::string fingerprint(const std::string& hash_name = "SHA-1") const; |
342 | | |
343 | | /** |
344 | | * Check if a certain DNS name matches up with the information in |
345 | | * the cert |
346 | | * @param name DNS name to match |
347 | | */ |
348 | | bool matches_dns_name(const std::string& name) const; |
349 | | |
350 | | /** |
351 | | * Check to certificates for equality. |
352 | | * @return true both certificates are (binary) equal |
353 | | */ |
354 | | bool operator==(const X509_Certificate& other) const; |
355 | | |
356 | | /** |
357 | | * Impose an arbitrary (but consistent) ordering, eg to allow sorting |
358 | | * a container of certificate objects. |
359 | | * @return true if this is less than other by some unspecified criteria |
360 | | */ |
361 | | bool operator<(const X509_Certificate& other) const; |
362 | | |
363 | | /** |
364 | | * Create a certificate from a data source providing the DER or |
365 | | * PEM encoded certificate. |
366 | | * @param source the data source |
367 | | */ |
368 | | explicit X509_Certificate(DataSource& source); |
369 | | |
370 | | #if defined(BOTAN_TARGET_OS_HAS_FILESYSTEM) |
371 | | /** |
372 | | * Create a certificate from a file containing the DER or PEM |
373 | | * encoded certificate. |
374 | | * @param filename the name of the certificate file |
375 | | */ |
376 | | explicit X509_Certificate(const std::string& filename); |
377 | | #endif |
378 | | |
379 | | /** |
380 | | * Create a certificate from a buffer |
381 | | * @param in the buffer containing the DER-encoded certificate |
382 | | */ |
383 | | explicit X509_Certificate(const std::vector<uint8_t>& in); |
384 | | |
385 | | /** |
386 | | * Create a certificate from a buffer |
387 | | * @param data the buffer containing the DER-encoded certificate |
388 | | * @param length length of data in bytes |
389 | | */ |
390 | | X509_Certificate(const uint8_t data[], size_t length); |
391 | | |
392 | | /** |
393 | | * Create an uninitialized certificate object. Any attempts to |
394 | | * access this object will throw an exception. |
395 | | */ |
396 | | X509_Certificate() = default; |
397 | | |
398 | 94.1k | X509_Certificate(const X509_Certificate& other) = default; |
399 | | |
400 | 0 | X509_Certificate& operator=(const X509_Certificate& other) = default; |
401 | | |
402 | | private: |
403 | | std::string PEM_label() const override; |
404 | | |
405 | | std::vector<std::string> alternate_PEM_labels() const override; |
406 | | |
407 | | void force_decode() override; |
408 | | |
409 | | const X509_Certificate_Data& data() const; |
410 | | |
411 | | std::shared_ptr<X509_Certificate_Data> m_data; |
412 | | }; |
413 | | |
414 | | /** |
415 | | * Check two certificates for inequality |
416 | | * @param cert1 The first certificate |
417 | | * @param cert2 The second certificate |
418 | | * @return true if the arguments represent different certificates, |
419 | | * false if they are binary identical |
420 | | */ |
421 | | BOTAN_PUBLIC_API(2,0) bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2); |
422 | | |
423 | | } |
424 | | |
425 | | #endif |